Class AWSFileStorage

Creates a new instance of AWSFileStorage.

Initializes the connection to AWS S3 using environment variables. Throws an error if any required environment variables are missing.

Checks if AWS S3 provider is properly configured. Returns true if access credentials and bucket name are present.

Copies an object within S3.

This method creates a copy of an object at a new location without removing the original. It uses the CopyObject API, which allows for copying objects within the same bucket.

Example

// Create a backup copy of an important file
const copied = await s3Storage.CopyObject(
  'documents/contract.pdf',
  'backups/contract_2024-05-16.pdf'
);

if (copied) {
  console.log('File copied successfully');
} else {
  console.log('Failed to copy file');
}
Copy

Creates a directory (virtual) in S3.

Since S3 doesn't have a native directory concept, this method creates a zero-byte object with a trailing slash to simulate a directory. The object has a special content type to indicate it's a directory.

Example

// Create a new directory structure
const created = await s3Storage.CreateDirectory('documents/reports/annual/');

if (created) {
  console.log('Directory created successfully');
} else {
  console.log('Failed to create directory');
}
Copy

Creates a pre-authenticated download URL for an object in S3.

This method generates a pre-signed URL that allows for downloading an object from S3 without needing AWS credentials. The URL is valid for 10 minutes and can be shared with clients.

Example

// Generate a pre-authenticated download URL for a PDF file
const downloadUrl = await s3Storage.CreatePreAuthDownloadUrl('documents/report.pdf');

// The URL can be shared with users or used in applications for direct download
console.log(downloadUrl);
Copy

Creates a pre-authenticated upload URL for an object in S3.

This method generates a pre-signed URL that allows for uploading an object to S3 without needing AWS credentials. The URL is valid for 10 minutes and includes the content type based on the file extension.

Example

// Generate a pre-authenticated upload URL for a PDF file
const { UploadUrl } = await s3Storage.CreatePreAuthUploadUrl('documents/report.pdf');

// The URL can be used with fetch or other HTTP clients to upload the file
console.log(UploadUrl);
Copy

Deletes a directory (virtual) and optionally its contents from S3.

For non-recursive deletion, this method simply deletes the directory placeholder object. For recursive deletion, it lists all objects with the directory path as prefix and deletes them using the DeleteObjects API, which allows for deleting up to 1000 objects in a single request.

Note: This implementation doesn't handle pagination for directories with more than 1000 objects. In a production environment, you might want to enhance this to handle such cases.

Example

// Delete an empty directory
const deleted = await s3Storage.DeleteDirectory('documents/temp/');

// Delete a directory and all its contents
const recursivelyDeleted = await s3Storage.DeleteDirectory('documents/old_projects/', true);
Copy

Deletes an object from S3.

This method attempts to delete the specified object. It returns true if the operation was successful, false otherwise.

Example

// Delete a temporary file
const deleted = await s3Storage.DeleteObject('temp/report-draft.pdf');

if (deleted) {
  console.log('File successfully deleted');
} else {
  console.log('Failed to delete file');
}
Copy

Checks if a directory (virtual) exists in S3.

Since S3 doesn't have a native directory concept, this method checks for either:

1. The existence of a directory placeholder object (zero-byte object with trailing slash)
2. The existence of any objects with the directory path as a prefix

Example

// Check if a directory exists before trying to save files to it
const exists = await s3Storage.DirectoryExists('documents/reports/');

if (!exists) {
  console.log('Directory does not exist, creating it first');
  await s3Storage.CreateDirectory('documents/reports/');
}

// Now safe to use the directory
await s3Storage.PutObject('documents/reports/new-report.pdf', fileData);
Copy

Downloads an object's content from S3.

This method retrieves the full content of an object using the GetObject API and returns it as a Buffer for processing in memory.

Throws

Error if the object doesn't exist or cannot be downloaded

Example

try {
  // For S3, objectId and fullPath are the same (both are the S3 key)
  const content = await s3Storage.GetObject({ fullPath: 'documents/config.json' });
  // Or equivalently:
  const content2 = await s3Storage.GetObject({ objectId: 'documents/config.json' });

  // Parse the JSON content
  const config = JSON.parse(content.toString('utf8'));
  console.log('Configuration loaded:', config);
} catch (error) {
  console.error('Failed to download file:', error.message);
}
Copy

Retrieves metadata for a specific object in S3.

This method fetches the properties of an object using the HeadObject API, which doesn't download the object content. This is more efficient for checking file attributes like size, content type, and last modified date.

Throws

Error if the object doesn't exist or cannot be accessed

Example

try {
  // For S3, objectId and fullPath are the same (both are the S3 key)
  const metadata = await s3Storage.GetObjectMetadata({ fullPath: 'documents/report.pdf' });
  // Or equivalently:
  const metadata2 = await s3Storage.GetObjectMetadata({ objectId: 'documents/report.pdf' });

  console.log(`File: ${metadata.name}`);
  console.log(`Size: ${metadata.size} bytes`);
  console.log(`Last modified: ${metadata.lastModified}`);
} catch (error) {
  console.error('File does not exist or cannot be accessed');
}
Copy

Lists objects with the specified prefix in S3.

This method returns a list of objects (files) and common prefixes (directories) under the specified path prefix. It uses the S3 ListObjectsV2 API which supports delimiter-based hierarchy simulation.

Example

// List all files and directories in the documents folder
const result = await s3Storage.ListObjects('documents/');

// Process files
for (const file of result.objects) {
  console.log(`File: ${file.name}, Size: ${file.size}, Type: ${file.contentType}`);
}

// Process subdirectories
for (const dir of result.prefixes) {
  console.log(`Directory: ${dir}`);
}
Copy

Moves an object from one location to another within S3.

Since S3 doesn't provide a native move operation, this method implements move as a copy followed by a delete operation. It first copies the object to the new location, and if successful, deletes the object from the original location.

Example

// Move a file from drafts to published folder
const success = await s3Storage.MoveObject(
  'drafts/report.docx',
  'published/final-report.docx'
);

if (success) {
  console.log('File successfully moved');
} else {
  console.log('Failed to move file');
}
Copy

Checks if an object exists in S3.

This method verifies the existence of an object using the HeadObject API, which doesn't download the object content. This is efficient for validation purposes.

Example

// Check if a file exists before attempting to use it
const exists = await s3Storage.ObjectExists('documents/report.pdf');

if (exists) {
  console.log('File exists, proceeding with download');
  const content = await s3Storage.GetObject('documents/report.pdf');
  // Process the content...
} else {
  console.log('File does not exist');
}
Copy

Uploads data to an object in S3.

This method directly uploads a Buffer of data to an object with the specified name. It's useful for server-side operations where you already have the data in memory.

Example

// Upload a text file
const content = Buffer.from('Hello, World!', 'utf8');
const uploaded = await s3Storage.PutObject(
  'documents/hello.txt',
  content,
  'text/plain',
  { author: 'John Doe', department: 'Engineering' }
);

if (uploaded) {
  console.log('File uploaded successfully');
} else {
  console.log('Failed to upload file');
}
Copy

Search is not supported by AWS S3. S3 is an object storage service without built-in search capabilities.

To search S3 objects, consider:

• Using AWS Athena to query S3 data
• Maintaining a separate search index (Elasticsearch, OpenSearch, etc.)
• Using S3 Select for querying individual objects
• Using S3 Inventory for listing and filtering objects

Throws

UnsupportedOperationError always