Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/opennebel/nestjs-s3client
A NestJS module for interacting with AWS S3. This module simplifies the integration of AWS S3 within a NestJS application by providing injectable services and configuration options.
https://github.com/opennebel/nestjs-s3client
aws-sdk aws-sdk-v3 nest nestjs nestjs-library s3 s3-bucket s3-storage
Last synced: about 1 month ago
JSON representation
A NestJS module for interacting with AWS S3. This module simplifies the integration of AWS S3 within a NestJS application by providing injectable services and configuration options.
- Host: GitHub
- URL: https://github.com/opennebel/nestjs-s3client
- Owner: OpenNebel
- License: mit
- Created: 2024-06-18T23:19:40.000Z (5 months ago)
- Default Branch: master
- Last Pushed: 2024-09-24T02:00:48.000Z (about 2 months ago)
- Last Synced: 2024-09-29T01:41:05.691Z (about 2 months ago)
- Topics: aws-sdk, aws-sdk-v3, nest, nestjs, nestjs-library, s3, s3-bucket, s3-storage
- Language: TypeScript
- Homepage: https://www.npmjs.com/package/@open-nebel/nest-s3
- Size: 2.51 MB
- Stars: 3
- Watchers: 1
- Forks: 0
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- Security: SECURITY.md
Awesome Lists containing this project
README
## @open-nebel/nest-s3
📖 **Docs**: [https://nestjs-s3.netlify.app](https://nestjs-s3.netlify.app/introduction)
A NestJS module for interacting with AWS S3. This module simplifies the integration of AWS S3 within a NestJS application by providing injectable services and configuration options.
**Note**: This library is compatible with AWS SDK V3.
> ⚠️ **AWS SDK Version 2.x Upcoming End-of-Support**
>
> We [announced](https://aws.amazon.com/blogs/developer/announcing-end-of-support-for-aws-sdk-for-javascript-v2) the upcoming end-of-support for AWS SDK for JavaScript v2. We recommend that you migrate to [AWS SDK for JavaScript v3](https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/welcome.html). For dates, additional details, and information on how to migrate, please refer to the linked announcement.
>
> The AWS SDK for JavaScript v3 is the latest and recommended version, which has been GA since December 2020. Here is [why and how you should use AWS SDK for JavaScript v3](https://aws.amazon.com/blogs/developer/why-and-how-you-should-use-aws-sdk-for-javascript-v3-on-node-js-18/). You can try our experimental migration scripts in [aws-sdk-js-codemod](https://www.npmjs.com/package/aws-sdk-js-codemod) to migrate your application from v2 to v3.
## Table of Contents
- [Installation](#installation)
- [Usage](#usage)
- [Configuration](#configuration)
- [Synchronous Configuration](#synchronous-configuration)
- [Asynchronous Configuration](#asynchronous-configuration)
- [Using the S3Service](#using-the-s3service)
- [Example Usage in a Service](#example-usage-in-a-service)
- [Available Methods](#available-methods)
- [getClient(): S3Client](#getclients3client)
- [createBucket(bucketName: string): Promise](#createbucketbucketname-string-promisevoid)
- [uploadObject(bucketName: string, key: string, body: string): Promise](#uploadobjectbucketname-string-key-string-body-string-promisevoid)
- [getObject(bucketName: string, key: string): Promise](#getobjectbucketname-string-key-string-promise-string--undefined)
- [deleteOneObject(bucketName: string, key: string): Promise](#deleteoneobjectbucketname-string-key-string-promisevoid)
- [deleteAllObjects(bucketName: string): Promise](#deleteallobjectsbucketname-string-promisevoid)
- [deleteBucket(bucketName: string): Promise](#deletebucketbucketname-string-promisevoid)
- [createPresignedUrlWithClient(params: { bucket: string; key: string }): Promise](#createpresignedurlwithclientparams--bucket-string-key-string--promisestring)
- [copyObject(sourceBucket: string, sourceKey: string, destinationBucket: string, destinationKey: string): Promise](#copyobjectsourcebucket-string-sourcekey-string-destinationbucket-string-destinationkey-string-promisevoid)
- [listBuckets(): Promise<{ owner: { name: string }; buckets: { name: string }[] }>](#listbuckets-promise-owner-name-string-buckets-name-string)
- [License](#license)
- [Contributing](#contributing)
- [Acknowledgements](#acknowledgements)
- [Support](#support)
## Installation
To install the package, use the following commands:
```bash
npm install @open-nebel/nest-s3 @aws-sdk/client-s3 @aws-sdk/s3-request-presigner
```
or
```bash
yarn add @open-nebel/nest-s3 @aws-sdk/client-s3 @aws-sdk/s3-request-presigner
```
## Usage
### Configuration
You can configure the S3 module using either synchronous or asynchronous configuration.
#### Synchronous Configuration
```typescript
import { Module } from '@nestjs/common';
import { S3Module } from '@open-nebel/nest-s3';
@Module({
imports: [
S3Module.forRoot({
region: 'your-region',
accessKeyId: 'your-access-key-id',
secretAccessKey: 'your-secret-access-key',
}),
],
})
export class AppModule {}
```
#### Asynchronous Configuration
```typescript
import { Module } from '@nestjs/common';
import { ConfigModule, ConfigService } from '@nestjs/config';
import { S3Module } from '@open-nebel/nest-s3';
@Module({
imports: [
ConfigModule.forRoot(),
S3Module.forRootAsync({
imports: [ConfigModule],
inject: [ConfigService],
useFactory: (configService: ConfigService) => ({
region: configService.get('AWS_REGION'),
accessKeyId: configService.get('AWS_ACCESS_KEY_ID'),
secretAccessKey: configService.get('AWS_SECRET_ACCESS_KEY'),
}),
}),
],
})
export class AppModule {}
```
### Using the S3Service
The `S3Service` provides methods to interact with AWS S3, such as creating buckets, uploading objects, and generating presigned URLs. Additionally, it exposes an instance of `S3Client` configured with the module settings, allowing direct interaction with S3.
#### Example Usage in a Service
```typescript
import { Injectable } from '@nestjs/common';
import { S3Service } from '@open-nebel/nest-s3';
import { S3Client, ListBucketsCommand } from '@aws-sdk/client-s3';
@Injectable()
export class MyService {
constructor(private readonly s3Service: S3Service) {}
async useS3ClientOriginal(): Promise {
const s3Client: S3Client = this.s3Service.getClient();
const buckets = await s3Client.send(new ListBucketsCommand({}));
console.log('Buckets:', buckets.Buckets);
}
async useS3Methods() {
const bucketName = 'your-bucket-name';
const key = 'your-file-key';
const body = 'your-file-content';
// Create a bucket
await this.s3Service.createBucket(bucketName);
// Upload an object
await this.s3Service.uploadObject(bucketName, key, body);
// Get an object
const objectContent = await this.s3Service.getObject(bucketName, key);
console.log('Object Content:', objectContent);
// Generate a presigned URL
const presignedUrl = await this.s3Service.createPresignedUrlWithClient({ bucket: bucketName, key });
console.log('Presigned URL:', presignedUrl);
// Delete an object
await this.s3Service.deleteOneObject(bucketName, key);
// Delete all objects in the bucket
await this.s3Service.deleteAllObjects(bucketName);
// Delete the bucket
await this.s3Service.deleteBucket(bucketName);
// Copy an object
await this.s3Service.copyObject('source-bucket', 'source-key', 'destination-bucket', 'destination-key');
// List all buckets
const { owner, buckets } = await this.s3Service.listBuckets();
console.log('Owner:', owner);
console.log('Buckets:', buckets);
}
}
```
## Available Methods
Given below are the available methods provided by the `S3Client` and `S3Service` classes.
### `getClient(): S3Client`
Returns the configured S3Client instance for direct interaction with AWS S3.
```typescript
const s3Client: S3Client = this.s3Service.getClient();
```
### `createBucket(bucketName: string): Promise`
Creates a new S3 bucket with the specified name.
```typescript
await this.s3Service.createBucket('my-new-bucket');
```
### `uploadObject(bucketName: string, key: string, body: string | Uint8Array | Buffer | ReadableStream | Blob): Promise`
Uploads an object to the specified S3 bucket.
```typescript
await this.s3Service.uploadObject('my-new-bucket', 'my-object-key', 'Hello, world!');
```
### `getObject(bucketName: string, key: string): Promise`
Retrieves an object from the specified S3 bucket.
```typescript
const content = await this.s3Service.getObject('my-new-bucket', 'my-object-key');
console.log('Object content:', content);
```
### `deleteOneObject(bucketName: string, key: string): Promise`
Deletes an object from the specified S3 bucket.
```typescript
await this.s3Service.deleteOneObject('my-new-bucket', 'my-object-key');
```
### `deleteAllObjects(bucketName: string): Promise`
Deletes all objects from the specified S3 bucket.
```typescript
await this.s3Service.deleteAllObjects('my-new-bucket');
```
### `deleteBucket(bucketName: string): Promise`
Deletes the specified S3 bucket.
```typescript
await this.s3Service.deleteBucket('my-new-bucket');
```
### `createPresignedUrlWithClient(params: { bucket: string; key: string }): Promise`
Generates a presigned URL for accessing an object in the specified S3 bucket.
```typescript
const presignedUrl = await this.s3Service.createPresignedUrlWithClient({ bucket: 'my-new-bucket', key: 'my-object-key' });
console.log('Presigned URL:', presignedUrl);
```
### `copyObject(sourceBucket: string, sourceKey: string, destinationBucket: string, destinationKey: string): Promise`
Copies an object from one bucket to another in AWS S3.
```typescript
await this.s3Service.copyObject('source-bucket', 'source-key', 'destination-bucket', 'destination-key');
```
### `listBuckets(): Promise<{ owner: { name: string }; buckets: { name: string }[] }>`
Lists all buckets in AWS S3.
```typescript
const { owner, buckets } = await this.s3Service.listBuckets();
console.log('Owner:', owner);
console.log('Buckets:', buckets);
```
## License
This project is licensed under the MIT License. See the [LICENSE](https://github.com/OpenNebel/Nest-AWS-SDK-V3-S3-CLIENT/blob/master/LICENCE.txt) file for details.
## Contributing
Contributions are welcome! Please feel free to submit a pull request or open an issue on GitHub.
## Acknowledgements
This package uses the AWS SDK for JavaScript (v3) and is inspired by the design principles of NestJS.
## Support
If you encounter any issues or have any questions, feel free to open an issue on GitHub or contact the maintainers.
---
By following this README, users should be able to easily install, configure, and use your NestJS AWS S3 library in their projects, with the added ability to directly interact with the AWS S3 client.