method

S3Client.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");

Referenced types

interface S3Options

Configuration options for S3 operations

  • accessKeyId?: string

    The access key ID for authentication. Defaults to S3_ACCESS_KEY_ID or AWS_ACCESS_KEY_ID environment variables.

  • acl?: 'private' | 'public-read' | 'public-read-write' | 'aws-exec-read' | 'authenticated-read' | 'bucket-owner-read' | 'bucket-owner-full-control' | 'log-delivery-write'

    The Access Control List (ACL) policy for the file. Controls who can access the file and what permissions they have.

    // Setting public read access
const file = s3.file("public-file.txt", {
  acl: "public-read",
  bucket: "my-bucket"
});
  • bucket?: string

    The S3 bucket name. Defaults to S3_BUCKET or AWS_BUCKET environment variables.

    // Using explicit bucket
const file = s3.file("my-file.txt", { bucket: "my-bucket" });
  • contentDisposition?: string

    The Content-Disposition header value. Controls how the file is presented when downloaded.

    // Setting attachment disposition with filename
const file = s3.file("report.pdf", {
  contentDisposition: "attachment; filename=\"quarterly-report.pdf\""
});
  • contentEncoding?: string

    The Content-Encoding header value. Specifies what content encodings have been applied to the object, for example to indicate that it has been compressed.

    // Setting gzip encoding
const file = s3.file("data.json.gz", {
  contentEncoding: "gzip"
});
  • endings?: EndingType
  • endpoint?: string

    The S3-compatible service endpoint URL. Defaults to S3_ENDPOINT or AWS_ENDPOINT environment variables.

    // AWS S3
const file = s3.file("my-file.txt", {
  endpoint: "https://s3.us-east-1.amazonaws.com"
});
  • partSize?: number

    The size of each part in multipart uploads (in bytes).

    • Minimum: 5 MiB
    • Maximum: 5120 MiB
    • Default: 5 MiB
    // Configuring multipart uploads
const file = s3.file("large-file.dat", {
  partSize: 10 * 1024 * 1024, // 10 MiB parts
  queueSize: 4  // Upload 4 parts in parallel
});

const writer = file.writer();
// ... write large file in chunks
  • queueSize?: number

    Number of parts to upload in parallel for multipart uploads.

    • Default: 5
    • Maximum: 255

    Increasing this value can improve upload speeds for large files but uses more memory.

  • region?: string

    The AWS region. Defaults to S3_REGION or AWS_REGION environment variables.

    const file = s3.file("my-file.txt", {
  bucket: "my-bucket",
  region: "us-west-2"
});
  • requestPayer?: boolean

    When set to true, confirms that the requester knows they will be charged for the request and data transfer costs. Required for accessing objects in Requester Pays buckets.

    // Accessing a file in a Requester Pays bucket
const file = s3.file("data.csv", {
  bucket: "requester-pays-bucket",
  requestPayer: true
});
const content = await file.text();
  • retry?: number

    Number of retry attempts for failed uploads.

    • Default: 3
    • Maximum: 255
    // Setting retry attempts
const file = s3.file("my-file.txt", {
  retry: 5 // Retry failed uploads up to 5 times
});
  • secretAccessKey?: string

    The secret access key for authentication. Defaults to S3_SECRET_ACCESS_KEY or AWS_SECRET_ACCESS_KEY environment variables.

  • sessionToken?: string

    Optional session token for temporary credentials. Defaults to S3_SESSION_TOKEN or AWS_SESSION_TOKEN environment variables.

    // Using temporary credentials
const file = s3.file("my-file.txt", {
  accessKeyId: tempAccessKey,
  secretAccessKey: tempSecretKey,
  sessionToken: tempSessionToken
});
  • storageClass?: 'STANDARD' | 'DEEP_ARCHIVE' | 'EXPRESS_ONEZONE' | 'GLACIER' | 'GLACIER_IR' | 'INTELLIGENT_TIERING' | 'ONEZONE_IA' | 'OUTPOSTS' | 'REDUCED_REDUNDANCY' | 'SNOW' | 'STANDARD_IA'

    The storage class for the object. By default, Amazon S3 stores newly created objects in the STANDARD storage class.

    // Setting an explicit storage class
const file = s3.file("my-file.json", {
  storageClass: "STANDARD_IA"
});
  • type?: string

    The Content-Type of the file. Automatically set based on file extension when possible.

    // Setting explicit content type
const file = s3.file("data.bin", {
  type: "application/octet-stream"
});
  • virtualHostedStyle?: boolean

    Use a virtual hosted-style endpoint, where the bucket name is part of the hostname. Defaults to false. When true, if endpoint is provided, the bucket option is ignored.

    // Using virtual hosted style
const file = s3.file("my-file.txt", {
  virtualHostedStyle: true,
  endpoint: "https://my-bucket.s3.us-east-1.amazonaws.com"
});

interface S3Stats