Class S3Client

A configured S3 bucket instance for managing files.

Example

// Basic bucket setup
const bucket = new S3Client({
  bucket: "my-bucket",
  accessKeyId: "key",
  secretAccessKey: "secret"
});
// Get file instance
const file = bucket.file("image.jpg");
await file.delete();

Index

Constructors

constructor

Methods

abortMultipartUpload bucketExists completeMultipartUpload createBucket createMultipartUpload deleteBucket deleteObjects file list listIterating listMultipartUploads listParts presign uploadPart

Constructors

constructor

new S3Client(options: S3ClientOptions): S3Client
Create a new instance of an S3 bucket so that credentials can be managed from a single instance instead of being passed to every method.
Parameters
- options: S3ClientOptions
  The default options to use for the S3 client.
Returns S3Client
- Defined in src/S3Client.ts:296

Methods

abortMultipartUpload

abortMultipartUpload(
    path: string,
    uploadId: string,
    options?: AbortMultipartUploadOptions,
): Promise<void>
Parameters
- path: string
- uploadId: string
- options: AbortMultipartUploadOptions = {}
Returns Promise<void>
Remarks
Uses AbortMultipartUpload.

Throws
If key is not at least 1 character long.

Throws
If uploadId is not provided.
- Defined in src/S3Client.ts:611

bucketExists

bucketExists(name: string, options?: BucketExistsOptions): Promise<boolean>
Checks if a bucket exists.
Parameters
- name: string
  The name of the bucket to delete. Same restrictions as in S3Client#createBucket.
- Optionaloptions: BucketExistsOptions
Returns Promise<boolean>
Throws
If the bucket name is invalid.

Remarks
Uses HeadBucket.
- Defined in src/S3Client.ts:937

completeMultipartUpload

completeMultipartUpload(
    path: string,
    uploadId: string,
    parts: readonly MultipartUploadPart[],
    options?: CompleteMultipartUploadOptions,
): Promise<CompleteMultipartUploadResult>
Parameters
- path: string
- uploadId: string
- parts: readonly MultipartUploadPart[]
- options: CompleteMultipartUploadOptions = {}
Returns Promise<CompleteMultipartUploadResult>
Remarks
Uses CompleteMultipartUpload.

Throws
If key is not at least 1 character long.

Throws
If uploadId is not provided.
- Defined in src/S3Client.ts:642

createBucket

createBucket(name: string, options?: BucketCreationOptions): Promise<void>
Creates a new bucket on the S3 server.
Parameters
- name: string
  The name of the bucket to create. AWS the name according to some rules. The most important ones are:
  
  Bucket names must be between 3 (min) and 63 (max) characters long.
  
  Bucket names can consist only of lowercase letters, numbers, periods (.), and hyphens (-).
  
  Bucket names must begin and end with a letter or number.
  
  Bucket names must not contain two adjacent periods.
  
  Bucket names must not be formatted as an IP address (for example, 192.168.5.4).
- Optionaloptions: BucketCreationOptions
Returns Promise<void>
Throws
If the bucket name is invalid.

Throws
If the bucket could not be created, e.g. if it already exists.

Remarks
Uses CreateBucket
- Defined in src/S3Client.ts:837

createMultipartUpload

createMultipartUpload(
key: string,
options?: CreateMultipartUploadOptions,
): Promise<CreateMultipartUploadResult>
Parameters
- key: string
- options: CreateMultipartUploadOptions = {}
Returns Promise<CreateMultipartUploadResult>
- Defined in src/S3Client.ts:474

deleteBucket

deleteBucket(name: string, options?: BucketDeletionOptions): Promise<void>
Deletes a bucket from the S3 server.
Parameters
- name: string
  The name of the bucket to delete. Same restrictions as in S3Client#createBucket.
- Optionaloptions: BucketDeletionOptions
Returns Promise<void>
Throws
If the bucket name is invalid.

Throws
If the bucket could not be deleted, e.g. if it is not empty.

Remarks
Uses DeleteBucket.
- Defined in src/S3Client.ts:905

deleteObjects

deleteObjects(
objects: readonly string[] | readonly S3BucketEntry[],
options?: DeleteObjectsOptions,
): Promise<DeleteObjectsResult>
Uses DeleteObjects to delete multiple objects in a single request.
Parameters
- objects: readonly string[] | readonly S3BucketEntry[]
- options: DeleteObjectsOptions = {}
Returns Promise<DeleteObjectsResult>
- Defined in src/S3Client.ts:1109

file

file(path: string, _options?: Partial<CreateFileInstanceOptions>): S3File
Creates an S3File instance for the given path.
Parameters
- path: string
  The path to the object in the bucket. Also known as object key. We recommend not using the following characters in a key name because of significant special character handling, which isn't consistent across all applications (see AWS docs):
  
  Backslash (\\)
  
  Left brace ({)
  
  Non-printable ASCII characters (128–255 decimal characters)
  
  Caret or circumflex (^)
  
  Right brace (})
  
  Percent character (%)
  
  Grave accent or backtick (```)
  
  Right bracket (])
  
  Quotation mark (")
  
  Greater than sign (>)
  
  Left bracket ([)
  
  Tilde (~)
  
  Less than sign (<)
  
  Pound sign (#)
  
  Vertical bar or pipe (|)
  
  lean-s3 does not enforce these restrictions.
- Optional_options: Partial<CreateFileInstanceOptions>
  TODO
Returns S3File
Example
```
const file = client.file("image.jpg");
await file.write(imageData);

const configFile = client.file("config.json", {
  type: "application/json",
  acl: "private"
});
```
- Defined in src/S3Client.ts:371

list

list(options?: ListObjectsOptions): Promise<ListObjectsResult>
Implements ListObjectsV2 to iterate over all keys.
Parameters
- options: ListObjectsOptions = {}
Returns Promise<ListObjectsResult>
Throws
If maxKeys is not between 1 and 1000.
- Defined in src/S3Client.ts:1008

listIterating

listIterating(
options: ListObjectsIteratingOptions,
): AsyncGenerator<S3BucketEntry>
Uses ListObjectsV2 to iterate over all keys. Pagination and continuation is handled internally.
Parameters
- options: ListObjectsIteratingOptions
Returns AsyncGenerator<S3BucketEntry>
- Defined in src/S3Client.ts:979

listMultipartUploads

listMultipartUploads(
options?: ListMultipartUploadsOptions,
): Promise<ListMultipartUploadsResult>
Parameters
- options: ListMultipartUploadsOptions = {}
Returns Promise<ListMultipartUploadsResult>
Remarks
Uses ListMultipartUploads.

Throws
If options.maxKeys is not between 1 and 1000.
- Defined in src/S3Client.ts:511

listParts

listParts(
    path: string,
    uploadId: string,
    options?: ListPartsOptions,
): Promise<ListPartsResult>
Parameters
- path: string
- uploadId: string
- options: ListPartsOptions = {}
Returns Promise<ListPartsResult>
Remarks
Uses ListParts.

Throws
If key is not at least 1 character long.

Throws
If uploadId is not provided.

Throws
If options.maxParts is not a number.

Throws
If options.maxParts is <= 0.

Throws
If options.partNumberMarker is not a string.
- Defined in src/S3Client.ts:753

presign

presign(
    path: string,
    __namedParameters?: Partial<
        S3FilePresignOptions & OverridableS3ClientOptions,
    >,
): string
Generate a presigned URL for temporary access to a file. Useful for generating upload/download URLs without exposing credentials.
Parameters
- path: string
- __namedParameters: Partial<S3FilePresignOptions & OverridableS3ClientOptions> = {}
Returns string
The operation on .path as a pre-signed URL.
Example
```
const downloadUrl = client.presign("file.pdf", {
  expiresIn: 3600 // 1 hour
});
```
- Defined in src/S3Client.ts:395

uploadPart

uploadPart(
    path: string,
    uploadId: string,
    data: UndiciBodyInit,
    partNumber: number,
    options?: UploadPartOptions,
): Promise<UploadPartResult>
Parameters
- path: string
- uploadId: string
- data: UndiciBodyInit
- partNumber: number
- options: UploadPartOptions = {}
Returns Promise<UploadPartResult>
Remarks
Uses UploadPart.

Throws
If key is not at least 1 character long.

Throws
If uploadId is not provided.
- Defined in src/S3Client.ts:698

Class S3Client

Example

Index

Constructors

Methods

Constructors

constructor

Parameters

Returns S3Client

Methods

abortMultipartUpload

Parameters

Returns Promise<void>

Remarks

Throws

Throws

bucketExists

Parameters

Returns Promise<boolean>

Throws

Remarks

completeMultipartUpload

Parameters

Returns Promise<CompleteMultipartUploadResult>

Remarks

Throws

Throws

createBucket

Parameters

Returns Promise<void>

Throws

Throws

Remarks

createMultipartUpload

Parameters

Returns Promise<CreateMultipartUploadResult>

deleteBucket

Parameters

Returns Promise<void>

Throws

Throws

Remarks

deleteObjects

Parameters

Returns Promise<DeleteObjectsResult>

file

Parameters

Returns S3File

Example

list

Parameters

Returns Promise<ListObjectsResult>

Throws

listIterating

Parameters

Returns AsyncGenerator<S3BucketEntry>

listMultipartUploads

Parameters

Returns Promise<ListMultipartUploadsResult>

Remarks

Throws

listParts

Parameters

Returns Promise<ListPartsResult>

Remarks

Throws

Throws

Throws

Throws

Throws

presign

Parameters

Returns string

Example

uploadPart

Parameters

Returns Promise<UploadPartResult>

Remarks

Throws

Throws