@ashkiani/s3-file-utils/README.md

List files in an S3 folder and generate signed URLs using AWS SDK v3.

# @ashkiani/s3-file-utils

AWS S3 utility functions for Node.js — list files in a folder, generate pre-signed download URLs, and **read objects as text/JSON** (BOM-tolerant) using AWS SDK v3.

This module helps backend applications interact with Amazon S3: listing folder contents, securely linking to files via expiring signed URLs, and fetching JSON files directly from S3.

---

## 📦 Installation

```bash
npm install @ashkiani/s3-file-utils
```

---

## 🛠 Usage

1. Set your environment variables:

```env
AWS_REGION=us-east-1
URL_EXPIRES_IN=3600
```

2. Use the module in your code:

```js
const s3Utils = require('@ashkiani/s3-file-utils');

const bucket = "my-bucket";
const folder = "documents/";

const files = await s3Utils.listFilesInFolder(bucket, folder);
console.log("Files:", files);

const signedUrl = await s3Utils.genSignedUrl(bucket, `${folder}${files[0]}`);
console.log("Download URL:", signedUrl);

const text = await s3Utils.getObjectText(bucket, `${folder}readme.txt`);
console.log("Text:", text);

const json = await s3Utils.getJson(bucket, `${folder}config.json`);
console.log("JSON:", json);
```

---

## 📘 API

### `listFilesInFolder(bucketName, folderPath)`

Lists all files (not folders) in a specific S3 folder.

* `bucketName` — Your S3 bucket name.
* `folderPath` — Must end with `/`, e.g., `"reports/2024/"`.
* Returns: `Promise<string[]>` sorted alphabetically.

### `genSignedUrl(bucket, fileKey)`

Generates a signed URL for a specific file in the bucket.

* `bucket` — S3 bucket name.
* `fileKey` — Full key including folder path.
* Returns: `Promise<string>` — A temporary download URL.

### `getObjectText(bucket, key)`

Retrieves an object from S3 and returns its contents as UTF-8 text.

* `bucket` — S3 bucket name.  
* `key` — Full key (path) to the object.  
* Returns: `Promise<string>`

### `getJson(bucket, key)`

Retrieves an object from S3, reads it as UTF-8 text, removes any UTF-8 BOM if present, and parses it as JSON.

* `bucket` — S3 bucket name.  
* `key` — Full key (path) to the JSON file.  
* Returns: `Promise<any>`

---

## 💡 Notes

* Uses AWS SDK v3 (`@aws-sdk/client-s3`, `@aws-sdk/s3-request-presigner`).
* Pre-signed URL expiration is controlled via `URL_EXPIRES_IN` environment variable (in seconds).
* Folder names must end with a `/` to properly scope the listing.
* Files are filtered to exclude subfolders and folder markers.
* getObjectText returns the object as UTF-8 without modifying content (no BOM stripping).
* getJson first removes a leading UTF-8 BOM (if present) and then parses; this avoids JSON.parse errors from Windows/.NET-saved files.

---

🧾 Changelog

1.1.0
Added getObjectText and getJson (BOM-tolerant S3 reads).

1.0.0
Initial release with listFilesInFolder and genSignedUrl.

---

## 📄 License

MIT © Siavash Ashkiani