@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

npm install @ashkiani/s3-file-utils

🛠 Usage

1. Set your environment variables:

AWS_REGION=us-east-1
URL_EXPIRES_IN=3600

2. Use the module in your code:

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