@nexus/storage-s3 (1.2.1)
Installation
@nexus:registry=npm install @nexus/storage-s3@1.2.1"@nexus/storage-s3": "1.2.1"About this package
@nexus/storage-s3
S3 storage plugin for the Nexus Framework, providing seamless integration with Amazon S3 and S3-compatible storage services.
Features
- 🚀 Easy integration with Nexus Framework
- 📁 Complete file operations (upload, download, delete, move)
- 🔒 ACL management support
- 🔗 Presigned URL generation
- 📝 Comprehensive logging
- ⚡ Support for custom S3-compatible endpoints
- 🔄 Proper error handling and type safety
Installation
npm install @nexus/storage-s3
Configuration
Add the plugin to your Nexus application:
import { S3StoragePlugin } from '@nexus/storage-s3';
// Initialize the plugin
const s3Plugin = new S3StoragePlugin({
region: 'us-east-1',
accessKeyId: 'your-access-key',
secretAccessKey: 'your-secret-key',
bucket: 'your-bucket-name',
endpoint: 'https://custom-endpoint.com' // Optional, for S3-compatible services
});
// Add to your Nexus application
app.usePlugin(s3Plugin);
Usage
Basic Operations
import { S3StorageService } from '@nexus/storage-s3';
export class YourService {
constructor(
@Inject(S3StorageService) private storage: S3StorageService
) {}
// Upload a file
async uploadFile(key: string, data: Buffer): Promise<string> {
return await this.storage.uploadObject(key, data, {
contentType: 'application/octet-stream'
});
}
// Download a file
async downloadFile(key: string): Promise<Buffer> {
return await this.storage.downloadObject(key);
}
// Delete a file
async deleteFile(key: string): Promise<void> {
await this.storage.deleteObject(key);
}
// Move/Rename a file
async moveFile(sourceKey: string, destinationKey: string): Promise<void> {
await this.storage.moveObject(sourceKey, destinationKey);
}
}
Advanced Features
Managing Access Control
import { ObjectCannedACL } from '@aws-sdk/client-s3';
// Set file permissions
await storage.setObjectAcl('file.txt', ObjectCannedACL.public_read);
// Upload with specific permissions
await storage.uploadObject('file.txt', data, {
acl: ObjectCannedACL.private
});
Generate Presigned URLs
// Generate a presigned URL that expires in 1 hour
const url = await storage.getPresignedUrl('file.txt', {
expiresIn: 3600 // seconds
});
API Reference
S3StorageService
Configuration
interface S3StorageServiceConfig {
endpoint?: string; // Optional custom endpoint
region: string; // AWS region
accessKeyId: string; // AWS access key ID
secretAccessKey: string;// AWS secret access key
bucket: string; // S3 bucket name
}
Methods
-
uploadObject(key: string, data: Buffer | Readable | string, options?: UploadOptions): Promise<string>- Uploads data to S3
- Returns the object key
- Options include
aclandcontentType
-
downloadObject(key: string): Promise<Buffer>- Downloads an object from S3
- Returns the object data as a Buffer
-
deleteObject(key: string): Promise<void>- Deletes an object from S3
-
moveObject(sourceKey: string, destinationKey: string): Promise<void>- Moves/renames an object in S3
-
setObjectAcl(key: string, acl: ObjectCannedACL): Promise<void>- Updates an object's ACL
-
getPresignedUrl(key: string, options?: PresignedUrlOptions): Promise<string>- Generates a presigned URL for temporary access
- Options include
expiresIn(seconds)
Error Handling
The service includes comprehensive error handling and logging. All operations will throw typed errors that include detailed information about what went wrong, making it easier to debug and handle errors appropriately in your application.
License
ISC
Dependencies
Dependencies
| ID | Version |
|---|---|
| @aws-sdk/client-s3 | ^3.712.0 |
| @aws-sdk/s3-request-presigner | ^3.712.0 |
Development Dependencies
| ID | Version |
|---|---|
| @nexus/core | ^0.3.0 |
| @rollup/plugin-typescript | ^12.1.2 |
| @swc/core | ^1.10.4 |
| ts-node | ^10.9.2 |
| tsc-alias | ^1.8.10 |
| tsup | ^8.3.5 |
| typescript | ^5.7.2 |
| vite-tsconfig-paths | ^5.1.4 |
| vitest | ^2.1.8 |
Peer Dependencies
| ID | Version |
|---|---|
| @nexus/core | ^0.3.0 |