or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

access-control-security.mdbucket-configuration.mdbucket-operations.mdclient-configuration.mdindex.mdlisting-pagination.mdmultipart-upload.mdobject-operations.mdwaiters-utilities.md
tile.json

index.mddocs/

AWS SDK for JavaScript S3 Client

AWS SDK for JavaScript S3 Client provides a comprehensive TypeScript/JavaScript interface for Amazon S3 (Simple Storage Service) operations. This library enables developers to interact with AWS S3 storage services programmatically with complete type safety, supporting all S3 operations including bucket management, object operations, multipart uploads, access control, lifecycle management, and advanced features.

Package Information

  • Package Name: @aws-sdk/client-s3
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @aws-sdk/client-s3
  • Requires Node.js: 18.0.0+
  • Platform Support: Node.js, Browser, React Native

Core Imports

import { S3Client, S3 } from "@aws-sdk/client-s3";
import { 
  PutObjectCommand, 
  GetObjectCommand, 
  ListObjectsV2Command 
} from "@aws-sdk/client-s3";

For CommonJS:

const { S3Client, S3, PutObjectCommand, GetObjectCommand } = require("@aws-sdk/client-s3");

Basic Usage

import { S3Client, PutObjectCommand, GetObjectCommand } from "@aws-sdk/client-s3";

// Create S3 client
const client = new S3Client({ 
  region: "us-east-1",
  credentials: {
    accessKeyId: "your-access-key",
    secretAccessKey: "your-secret-key"
  }
});

// Upload an object
const putCommand = new PutObjectCommand({
  Bucket: "my-bucket",
  Key: "my-file.txt",
  Body: "Hello, S3!",
  ContentType: "text/plain"
});
await client.send(putCommand);

// Download an object
const getCommand = new GetObjectCommand({
  Bucket: "my-bucket",
  Key: "my-file.txt"
});
const response = await client.send(getCommand);
const content = await response.Body?.transformToString();

Architecture

The AWS S3 client is built around several key architectural patterns:

  • Command Pattern: All operations are implemented as command classes (e.g., PutObjectCommand, GetObjectCommand)
  • Client Interface: Two main client patterns - S3Client for individual commands, S3 for aggregated methods
  • Smithy Framework: Built on AWS Smithy for type-safe API generation and protocol handling
  • Middleware Pipeline: Extensible middleware system for authentication, retry logic, and request/response processing
  • Platform Abstraction: Runtime-specific configurations for Node.js, browsers, and React Native
  • Streaming Support: Built-in support for streaming large objects and multipart uploads

Capabilities

Client Management

Core client initialization and configuration for connecting to Amazon S3 services.

class S3Client {
  constructor(configuration: S3ClientConfig);
  send<InputType, OutputType>(
    command: Command<InputType, OutputType, S3ClientResolvedConfig>
  ): Promise<OutputType>;
  destroy(): void;
}

interface S3ClientConfig {
  region?: string | Provider<string>;
  credentials?: AwsCredentialIdentityProvider;
  endpoint?: string | EndpointV2 | Provider<EndpointV2>;
  maxAttempts?: number | Provider<number>;
  retryMode?: string | Provider<string>;
  // ... additional configuration options
}

Client Configuration

Bucket Operations

Complete bucket management including creation, deletion, configuration, and policy management.

class CreateBucketCommand {
  constructor(input: CreateBucketCommandInput);
}

interface CreateBucketCommandInput {
  Bucket: string;
  ACL?: BucketCannedACL;
  CreateBucketConfiguration?: CreateBucketConfiguration;
  GrantFullControl?: string;
  GrantRead?: string;
  GrantReadACP?: string;
  GrantWrite?: string;
  GrantWriteACP?: string;
  ObjectLockEnabledForBucket?: boolean;
}

Bucket Operations

Object Operations

Core object storage operations including upload, download, copy, and metadata management.

class PutObjectCommand {
  constructor(input: PutObjectCommandInput);
}

interface PutObjectCommandInput {
  Bucket: string;
  Key: string;
  Body?: StreamingBlobPayloadInputTypes;
  ACL?: ObjectCannedACL;
  ContentType?: string;
  ContentLength?: number;
  Metadata?: Record<string, string>;
  StorageClass?: StorageClass;
  ServerSideEncryption?: ServerSideEncryption;
  // ... additional object properties
}

Object Operations

Multipart Upload

Efficient handling of large file uploads through multipart upload operations.

class CreateMultipartUploadCommand {
  constructor(input: CreateMultipartUploadCommandInput);
}

interface CreateMultipartUploadCommandInput {
  Bucket: string;
  Key: string;
  ACL?: ObjectCannedACL;
  ContentType?: string;
  Metadata?: Record<string, string>;
  StorageClass?: StorageClass;
  ServerSideEncryption?: ServerSideEncryption;
  // ... additional upload properties
}

Multipart Upload

Access Control & Security

Comprehensive access control through ACLs, policies, and IAM integration.

class PutBucketAclCommand {
  constructor(input: PutBucketAclCommandInput);
}

interface PutBucketAclCommandInput {
  Bucket: string;
  ACL?: BucketCannedACL;
  AccessControlPolicy?: AccessControlPolicy;
  GrantFullControl?: string;
  GrantRead?: string;
  GrantReadACP?: string;
  GrantWrite?: string;
  GrantWriteACP?: string;
}

Access Control & Security

Bucket Configuration

Advanced bucket features including versioning, lifecycle, encryption, and notification settings.

class PutBucketVersioningCommand {
  constructor(input: PutBucketVersioningCommandInput);
}

interface PutBucketVersioningCommandInput {
  Bucket: string;
  VersioningConfiguration: VersioningConfiguration;
  MFA?: string;
}

interface VersioningConfiguration {
  MfaDelete?: MfaDelete;
  Status?: BucketVersioningStatus;
}

Bucket Configuration

Listing & Pagination

Efficient listing of buckets, objects, and multipart uploads with built-in pagination support.

class ListObjectsV2Command {
  constructor(input: ListObjectsV2CommandInput);
}

interface ListObjectsV2CommandInput {
  Bucket: string;
  ContinuationToken?: string;
  Delimiter?: string;
  MaxKeys?: number;
  Prefix?: string;
  StartAfter?: string;
}

Listing & Pagination

Waiters & Utilities

Built-in waiters for polling operations and utility functions for common tasks.

function waitUntilBucketExists(
  params: WaiterConfiguration<S3Client>,
  input: HeadBucketCommandInput
): Promise<WaiterResult>;

function waitUntilObjectExists(
  params: WaiterConfiguration<S3Client>,
  input: HeadObjectCommandInput
): Promise<WaiterResult>;

Waiters & Utilities

Common Types

// Storage classes
type StorageClass = 
  | "STANDARD"
  | "STANDARD_IA" 
  | "ONEZONE_IA"
  | "INTELLIGENT_TIERING"
  | "GLACIER"
  | "DEEP_ARCHIVE"
  | "GLACIER_IR"
  | "EXPRESS_ONEZONE";

// Server-side encryption options
type ServerSideEncryption = "AES256" | "aws:kms" | "aws:kms:dsse";

// Object permissions
type ObjectCannedACL = 
  | "private"
  | "public-read" 
  | "public-read-write"
  | "authenticated-read"
  | "aws-exec-read"
  | "bucket-owner-read"
  | "bucket-owner-full-control";

// Core data structures
interface Object {
  Key?: string;
  LastModified?: Date;
  ETag?: string;
  Size?: number;
  StorageClass?: ObjectStorageClass;
  Owner?: Owner;
}

interface Owner {
  DisplayName?: string;
  ID?: string;
}

interface Tag {
  Key: string;
  Value: string;
}

// Exception handling
class S3ServiceException extends Error {
  name: string;
  $fault: "client" | "server";
  $metadata: ResponseMetadata;
}