DocsReferenceGuidesBlog
Discord logo
Discord
GitHub logo

S3Client

Bun

Symbol

S3Client

class S3Client

A configured S3 bucket instance for managing files. The instance is callable to create S3File instances and provides methods for common operations.

// Basic bucket setup
    const bucket = new S3Client({
      bucket: "my-bucket",
      accessKeyId: "key",
      secretAccessKey: "secret"
    });

    // Get file instance
    const file = bucket.file("image.jpg");

    // Common operations
    await bucket.write("data.json", JSON.stringify({hello: "world"}));
    const url = bucket.presign("file.pdf");
    await bucket.unlink("old.txt");
  • delete(path: string, options?: S3Options): Promise<void>

    Delete a file from the bucket. Alias for S3Client.unlink.

    @param path

    The path to the file in the bucket

    @param options

    Additional S3 options to override defaults

    @returns

    A promise that resolves when deletion is complete

    // Simple delete
    await bucket.delete("old-file.txt");

    // With error handling
    try {
      await bucket.delete("file.dat");
      console.log("File deleted");
    } catch (err) {
      console.error("Delete failed:", err);
    }
  • exists(path: string, options?: S3Options): Promise<boolean>

    Check if a file exists in the bucket. Uses HEAD request to check existence.

    @param path

    The path to the file in the bucket

    @param options

    Additional S3 options to override defaults

    @returns

    A promise that resolves to true if the file exists, false otherwise

    // Check existence
    if (await bucket.exists("config.json")) {
      const file = bucket.file("config.json");
      const config = await file.json();
    }

    // With error handling
    try {
      if (!await bucket.exists("required.txt")) {
        throw new Error("Required file missing");
      }
    } catch (err) {
      console.error("Check failed:", err);
    }
  • file(path: string, options?: S3Options): S3File

    Creates an S3File instance for the given path.

    @param path

    The path to the file in the bucket

    @param options

    Additional S3 options to override defaults

    @returns

    An S3File instance

    const file = bucket.file("image.jpg");
    await file.write(imageData);

    const configFile = bucket.file("config.json", {
      type: "application/json",
      acl: "private"
    });
  • list(input?: null | S3ListObjectsOptions, options?: Pick<S3Options, 'accessKeyId' | 'secretAccessKey' | 'sessionToken' | 'region' | 'bucket' | 'endpoint'>): Promise<S3ListObjectsResponse>

    Returns some or all (up to 1,000) of the objects in a bucket with each request.

    You can use the request parameters as selection criteria to return a subset of the objects in a bucket.

    @param input

    Options for listing objects in the bucket

    @param options

    Additional S3 options to override defaults

    @returns

    A promise that resolves to the list response

    // List (up to) 1000 objects in the bucket
    const allObjects = await bucket.list();

    // List (up to) 500 objects under `uploads/` prefix, with owner field for each object
    const uploads = await bucket.list({
      prefix: 'uploads/',
      maxKeys: 500,
      fetchOwner: true,
    });

    // Check if more results are available
    if (uploads.isTruncated) {
      // List next batch of objects under `uploads/` prefix
      const moreUploads = await bucket.list({
        prefix: 'uploads/',
        maxKeys: 500,
        startAfter: uploads.contents!.at(-1).key
        fetchOwner: true,
      });
    }
  • presign(path: string, options?: S3FilePresignOptions): string

    Generate a presigned URL for temporary access to a file. Useful for generating upload/download URLs without exposing credentials.

    @param path

    The path to the file in the bucket

    @param options

    Options for generating the presigned URL

    @returns

    A presigned URL string

    // Download URL
    const downloadUrl = bucket.presign("file.pdf", {
      expiresIn: 3600 // 1 hour
    });

    // Upload URL
    const uploadUrl = bucket.presign("uploads/image.jpg", {
      method: "PUT",
      expiresIn: 3600,
      type: "image/jpeg",
      acl: "public-read"
    });

    // Long-lived public URL
    const publicUrl = bucket.presign("public/doc.pdf", {
      expiresIn: 7 * 24 * 60 * 60, // 7 days
      acl: "public-read"
    });
  • size(path: string, options?: S3Options): Promise<number>

    Get the size of a file in bytes. Uses HEAD request to efficiently get size.

    @param path

    The path to the file in the bucket

    @param options

    Additional S3 options to override defaults

    @returns

    A promise that resolves to the file size in bytes

    // Get size
    const bytes = await bucket.size("video.mp4");
    console.log(`Size: ${bytes} bytes`);

    // Check if file is large
    if (await bucket.size("data.zip") > 100 * 1024 * 1024) {
      console.log("File is larger than 100MB");
    }
  • stat(path: string, options?: S3Options): Promise<S3Stats>

    Get the stat of a file in an S3-compatible storage service.

    @param path

    The path to the file in the bucket

    @param options

    Additional S3 options to override defaults

    @returns

    A promise that resolves to the file stats

    const stat = await bucket.stat("my-file.txt");
  • write(path: string, data: string | ArrayBuffer | SharedArrayBuffer | Request | Response | Blob | File | BunFile | ArrayBufferView<ArrayBufferLike> | S3File, options?: S3Options): Promise<number>

    Writes data directly to a path in the bucket. Supports strings, buffers, streams, and web API types.

    @param path

    The path to the file in the bucket

    @param data

    The data to write to the file

    @param options

    Additional S3 options to override defaults

    @returns

    The number of bytes written

    // Write string
    await bucket.write("hello.txt", "Hello World");

    // Write JSON with type
    await bucket.write(
      "data.json",
      JSON.stringify({hello: "world"}),
      {type: "application/json"}
    );

    // Write from fetch
    const res = await fetch("https://example.com/data");
    await bucket.write("data.bin", res);

    // Write with ACL
    await bucket.write("public.html", html, {
      acl: "public-read",
      type: "text/html"
    });
  • static delete(path: string, options?: S3Options): Promise<void>

    Delete a file from the bucket. Alias for S3Client.unlink.

    @param path

    The path to the file in the bucket

    @param options

    S3 credentials and configuration options

    @returns

    A promise that resolves when deletion is complete

    // Simple delete
    await S3Client.delete("old-file.txt", credentials);

    // With error handling
    try {
      await S3Client.delete("file.dat", credentials);
      console.log("File deleted");
    } catch (err) {
      console.error("Delete failed:", err);
    }
  • static exists(path: string, options?: S3Options): Promise<boolean>

    Check if a file exists in the bucket. Uses HEAD request to check existence.

    @param path

    The path to the file in the bucket

    @param options

    S3 credentials and configuration options

    @returns

    A promise that resolves to true if the file exists, false otherwise

    // Check existence
    if (await S3Client.exists("config.json", credentials)) {
      const file = bucket.file("config.json");
      const config = await file.json();
    }

    // With error handling
    try {
      if (!await S3Client.exists("required.txt", credentials)) {
        throw new Error("Required file missing");
      }
    } catch (err) {
      console.error("Check failed:", err);
    }
  • static file(path: string, options?: S3Options): S3File

    Creates an S3File instance for the given path.

    @param path

    The path to the file in the bucket

    @param options

    S3 credentials and configuration options

    @returns

    An S3File instance

    const file = S3Client.file("image.jpg", credentials);
    await file.write(imageData);

    const configFile = S3Client.file("config.json", {
      ...credentials,
      type: "application/json",
      acl: "private"
    });
  • static list(input?: null | S3ListObjectsOptions, options?: Pick<S3Options, 'accessKeyId' | 'secretAccessKey' | 'sessionToken' | 'region' | 'bucket' | 'endpoint'>): Promise<S3ListObjectsResponse>

    Returns some or all (up to 1,000) of the objects in a bucket with each request.

    You can use the request parameters as selection criteria to return a subset of the objects in a bucket.

    @param input

    Options for listing objects in the bucket

    @param options

    S3 credentials and configuration options

    @returns

    A promise that resolves to the list response

    // List (up to) 1000 objects in the bucket
    const allObjects = await S3Client.list(null, credentials);

    // List (up to) 500 objects under `uploads/` prefix, with owner field for each object
    const uploads = await S3Client.list({
      prefix: 'uploads/',
      maxKeys: 500,
      fetchOwner: true,
    }, credentials);

    // Check if more results are available
    if (uploads.isTruncated) {
      // List next batch of objects under `uploads/` prefix
      const moreUploads = await S3Client.list({
        prefix: 'uploads/',
        maxKeys: 500,
        startAfter: uploads.contents!.at(-1).key
        fetchOwner: true,
      }, credentials);
    }
  • static presign(path: string, options?: S3FilePresignOptions): string

    Generate a presigned URL for temporary access to a file. Useful for generating upload/download URLs without exposing credentials.

    @param path

    The path to the file in the bucket

    @param options

    S3 credentials and presigned URL configuration

    @returns

    A presigned URL string

    // Download URL
    const downloadUrl = S3Client.presign("file.pdf", {
      ...credentials,
      expiresIn: 3600 // 1 hour
    });

    // Upload URL
    const uploadUrl = S3Client.presign("uploads/image.jpg", {
      ...credentials,
      method: "PUT",
      expiresIn: 3600,
      type: "image/jpeg",
      acl: "public-read"
    });

    // Long-lived public URL
    const publicUrl = S3Client.presign("public/doc.pdf", {
      ...credentials,
      expiresIn: 7 * 24 * 60 * 60, // 7 days
      acl: "public-read"
    });
  • static size(path: string, options?: S3Options): Promise<number>

    Get the size of a file in bytes. Uses HEAD request to efficiently get size.

    @param path

    The path to the file in the bucket

    @param options

    S3 credentials and configuration options

    @returns

    A promise that resolves to the file size in bytes

    // Get size
    const bytes = await S3Client.size("video.mp4", credentials);
    console.log(`Size: ${bytes} bytes`);

    // Check if file is large
    if (await S3Client.size("data.zip", credentials) > 100 * 1024 * 1024) {
      console.log("File is larger than 100MB");
    }
  • static stat(path: string, options?: S3Options): Promise<S3Stats>

    Get the stat of a file in an S3-compatible storage service.

    @param path

    The path to the file in the bucket

    @param options

    S3 credentials and configuration options

    @returns

    A promise that resolves to the file stats

    const stat = await S3Client.stat("my-file.txt", credentials);
  • static write(path: string, data: string | ArrayBuffer | SharedArrayBuffer | Request | Response | Blob | File | BunFile | ArrayBufferView<ArrayBufferLike> | S3File, options?: S3Options): Promise<number>

    Writes data directly to a path in the bucket. Supports strings, buffers, streams, and web API types.

    @param path

    The path to the file in the bucket

    @param data

    The data to write to the file

    @param options

    S3 credentials and configuration options

    @returns

    The number of bytes written

    // Write string
    await S3Client.write("hello.txt", "Hello World", credentials);

    // Write JSON with type
    await S3Client.write(
      "data.json",
      JSON.stringify({hello: "world"}),
      {
        ...credentials,
        type: "application/json"
      }
    );

    // Write from fetch
    const res = await fetch("https://example.com/data");
    await S3Client.write("data.bin", res, credentials);

    // Write with ACL
    await S3Client.write("public.html", html, {
      ...credentials,
      acl: "public-read",
      type: "text/html"
    });