@hdriel/aws-utils 1.1.3 → 1.1.5

package/README.md

@@ -2,6 +2,7 @@
 
 A powerful, type-safe wrapper around AWS S3 SDK v3 that simplifies S3 operations with advanced features like streaming, file uploads, directory management, and LocalStack support.
 
+
 ## Features
 
 ✨ **Simplified API** - Clean, intuitive methods for common S3 operations  
@@ -15,6 +16,11 @@ A powerful, type-safe wrapper around AWS S3 SDK v3 that simplifies S3 operations
 ⚡ **Connection Pooling** - Optimized HTTP/HTTPS agents for better performance  
 📊 **Pagination** - Built-in pagination for large directory listings
 
+# FULL DEMO PROJECT EXAMPLE:
+please see this project code before using: [aws-utils-demo github link!](https://github.com/hdriel/aws-utils-demo)
+![Main Screen - Preview](readme-assets/demo-bucket-image-preview.webp)
+
+
 ## Installation
 
 ```bash
@@ -98,8 +104,9 @@ interface S3UtilProps {
 ```
 ----
 
-# FULL DEMO PROJECT EXAMPLE: 
-please see this project code before using: [AWS-UTILS-DEMO github linke](https://github.com/hdriel/aws-utils-demo)
+# FULL DEMO PROJECT EXAMPLE:
+please see this project code before using: [aws-utils-demo github link!](https://github.com/hdriel/aws-utils-demo)
+![Main Screen - Preview](readme-assets/login-screen.webp)
 
 
 ---
@@ -107,27 +114,19 @@ please see this project code before using: [AWS-UTILS-DEMO github linke](https:/
 
 ## Core Features
 
-### 🪣 Bucket Operations
+### C.R.U.D Bucket Operations
 
-#### Initialize Bucket
 ```typescript
-// Create private bucket
-await s3.initBucket('private');
-
-// Create public bucket
-await s3.initBucket('public-read');
-
-// With location constraint
-await s3.initBucket('private', { 
-  includeConstraintLocation: true 
-});
-```
+// CREATE
+await s3.initBucket('private'); // Create private bucket (if not exists)
+await s3.initBucket('public-read'); // Create public bucket (if not exists)
+// Could provided includeConstraintLocation option, like:  
+await s3.initBucket('private', { includeConstraintLocation: true} );
 
-#### Bucket Information
-```typescript
+// READ
+const exists = await s3.isBucketExists(); // check for existance bucket
 const info = await s3.bucketInfo();
-console.log(info);
-// {
+// info = {
 //   name: 'my-bucket',
 //   region: 'us-east-1',
 //   exists: true,
@@ -137,44 +136,47 @@ console.log(info);
 //   publicAccessBlock: { ... },
 //   policy: { ... }
 // }
-```
 
-#### Check Bucket Exists
-```typescript
-const exists = await s3.isBucketExists();
-```
+const buckets = await s3.getBucketList(); // get all bucket list from aws s3 storage
+// Could get bucket list with public access info like: 
+/*
+bucket list option: {
+    Name?: string | undefined;
+    CreationDate?: Date | undefined;
+    BucketRegion?: string | undefined;
+    BucketArn?: string | undefined;
+    PublicAccessBlockConfiguration: {    
+        BlockPublicAcls?: boolean | undefined;
+        IgnorePublicAcls?: boolean | undefined;
+        BlockPublicPolicy?: boolean | undefined;
+        RestrictPublicBuckets?: boolean | undefined;
+    }
+}
+*/
+const bucketsWithAccess = await s3.getBucketList({ includePublicAccess: true });
 
-#### Delete Bucket
-```typescript
-// Delete bucket (must be empty)
-await s3.destroyBucket();
+// UPDATE
+s3.changeBucket('another-bucket'); // Switch to different bucket 
 
-// Force delete with all contents
-await s3.destroyBucket(true);
+// DELETE
+await s3.destroyBucket(); // delete empty bucket
+await s3.destroyBucket(true); // Force delete with all contents and bucket
 ```
 
-#### List All Buckets
-```typescript
-const buckets = await s3.getBucketList();
-
-// Include public access configuration
-const bucketsWithAccess = await s3.getBucketList({ 
-  includePublicAccess: true 
-});
-```
+### 📁 C.R.U.D Directory Operations
 
-### 📁 Directory Operations
+* auto decodeURIComponent for all directory input params
+* handle directory issue (no matter if prefix/postfix slashes)
 
 #### Create Directory
 ```typescript
+// CREATE
 await s3.createDirectory('/uploads/images');
-```
 
-#### List Directory Contents
-```typescript
+// READ
+const exists = await s3.directoryExists('/uploads/images'); // check for existance directory
 const { directories, files } = await s3.directoryList('/uploads');
-
-console.log('Subdirectories:', directories);
+console.log('Subdirectories:', directories); // string[] directories like: ['images', 'test']
 console.log('Files:', files);
 // files: [
 //   {
@@ -185,36 +187,24 @@ console.log('Files:', files);
 //     Location: 'https://...'
 //   }
 // ]
-```
 
-#### Paginated Directory Listing
-```typescript
 // Get second page with 50 items per page
-const result = await s3.directoryListPaginated('/uploads', {
-  pageSize: 50,
-  pageNumber: 1
+const { directories, files, totalFetched } = await s3.directoryListPaginated('/uploads', {
+    pageSize: 50,
+    pageNumber: 1 // pageNumber is zero base (0-page one, 1- page two, ...)
 });
 
-console.log(result.directories); // Array of directory names
-console.log(result.files);       // Array of file objects
-console.log(result.totalFetched); // Number of items returned
-```
+// DELETE
+await s3.deleteDirectory('/uploads/temp'); // Delete directory and all contents
 
-#### Delete Directory
-```typescript
-// Delete directory and all contents
-await s3.deleteDirectory('/uploads/temp');
 ```
 
-#### Check Directory Exists
-```typescript
-const exists = await s3.directoryExists('/uploads/images');
-```
 
-### 📄 File Operations
+### 📄 C.R.U.D File Operations
 
-#### Upload File
 ```typescript
+// CREATE
+// > Upload File
 import { ACLs } from '@hdriel/aws-utils';
 
 // Upload buffer
@@ -225,79 +215,45 @@ await s3.uploadFile('/public/image.jpg', buffer, ACLs.public_read);
 
 // Upload with version tag
 await s3.uploadFile('/docs/v2.pdf', buffer, ACLs.private, '2.0.0');
-```
-
-#### Check File Exists
-```typescript
-const exists = await s3.fileExists('/documents/file.pdf');
-```
-
-#### Get File Content
-```typescript
-// As buffer
-const buffer = await s3.fileContent('/documents/file.pdf');
 
-// As base64 string
-const base64 = await s3.fileContent('/image.jpg', 'base64');
+// >  Generate Presigned URL
+const url = await s3.fileUrl('/private/document.pdf'); // Expires in 15 minutes (default)
+const url = await s3.fileUrl('/private/document.pdf', '1h'); // Custom expiration in string value
+const url = await s3.fileUrl('/private/document.pdf', 3600); // Custom expiration in seconds value
 
-// As UTF-8 string
-const text = await s3.fileContent('/data.json', 'utf8');
-```
-
-#### File Information
-```typescript
+// READ
+const exists = await s3.fileExists('/documents/file.pdf'); // check for existance file
 const info = await s3.fileInfo('/documents/file.pdf');
-console.log(info.ContentLength);
-console.log(info.ContentType);
-console.log(info.LastModified);
-```
+const files = await s3.fileListInfo('/documents'); // List all files in directory
+const pdfFiles = await s3.fileListInfo('/documents', 'report-'); // List files with prefix
+// Paginated file listing - Recommanded way!
+const { files, totalFetched } = await s3.fileListInfoPaginated('/documents', { 
+    fileNamePrefix: 'invoice-',
+    pageSize: 100,
+    pageNumber: 0
+});
+const version = await s3.fileVersion('/documents/file.pdf'); // Get file version
 
-#### List Files
-```typescript
-// List all files in directory
-const files = await s3.fileListInfo('/documents');
 
-// List files with prefix
-const pdfFiles = await s3.fileListInfo('/documents', 'report-');
+// > Get File Content
+const buffer = await s3.fileContent('/documents/file.pdf'); // As buffer
+const base64 = await s3.fileContent('/image.jpg', 'base64'); // As base64 string
+const text = await s3.fileContent('/data.json', 'utf8'); // As UTF-8 string
 
-// Paginated file listing
-const { files, totalFetched } = await s3.fileListInfoPaginated('/documents', {
-  fileNamePrefix: 'invoice-',
-  pageSize: 100,
-  pageNumber: 0
-});
-```
-
-#### File Size
-```typescript
+// > Get File Size
 const bytes = await s3.sizeOf('/large-file.zip');
 const kb = await s3.sizeOf('/large-file.zip', 'KB');
 const mb = await s3.sizeOf('/large-file.zip', 'MB');
 const gb = await s3.sizeOf('/large-file.zip', 'GB');
-```
 
-#### Delete File
-```typescript
-await s3.deleteFile('/documents/old-file.pdf');
-```
+// UPDATE 
+// > File Tagging
+await s3.taggingFile('/documents/file.pdf', {Key: 'version', Value: '1.0.0'}); // Tag file with version
 
-#### Generate Presigned URL
-```typescript
-// Expires in 15 minutes (default)
-const url = await s3.fileUrl('/private/document.pdf');
-
-// Custom expiration
-const url = await s3.fileUrl('/private/document.pdf', '1h');
-const url = await s3.fileUrl('/private/document.pdf', 3600); // seconds
-```
 
-#### File Tagging
-```typescript
-// Tag file with version
-await s3.taggingFile('/documents/file.pdf', '1.0.0');
+// DELETE 
+await s3.deleteFile('/documents/old-file.pdf');
 
-// Get file version
-const version = await s3.fileVersion('/documents/file.pdf');
 ```
 
 ### 🎬 Streaming & Express.js Integration
@@ -487,11 +443,10 @@ import { S3LocalstackUtil } from '@hdriel/aws-utils';
 
 const s3 = new S3LocalstackUtil({
   bucket: 'test-bucket',
-  endpoint: 'http://localhost:4566',
-  region: 'us-east-1',
-  accessKeyId: 'test',
-  secretAccessKey: 'test',
-  s3ForcePathStyle: true
+  // endpoint: 'http://localhost:4566', // get from .env file
+  // region: 'us-east-1', // get from .env file
+  // accessKeyId: 'test', // get from .env file
+  // secretAccessKey: 'test', // get from .env file
 });
 
 // Use same API as S3Util
@@ -540,19 +495,6 @@ services:
 
 ### Dynamic Bucket Switching
 
-```typescript
-const s3 = new S3Util({
-  bucket: 'default-bucket',
-  // ... other config
-});
-
-// Switch to different bucket
-s3.changeBucket('another-bucket');
-
-// Operations now use 'another-bucket'
-await s3.fileExists('/file.txt');
-```
-
 ### Custom Logger Integration
 
 ```typescript
@@ -561,9 +503,9 @@ import { Logger } from 'stack-trace-logger';
 const logger = new Logger('S3Service');
 
 const s3 = new S3Util({
-  bucket: 'my-bucket',
-  logger,
-  reqId: 'request-123'
+    bucket: 'my-bucket',
+    reqId: 'request-123', 
+    logger,
 });
 
 // All operations will log with your logger
@@ -582,152 +524,16 @@ The utility includes optimized HTTP/HTTPS agents:
 // - socketTimeout: 30000ms
 ```
 
-### Batch Operations
-
-```typescript
-// Upload multiple files in parallel
-const files = [
-  { path: '/docs/file1.pdf', data: buffer1 },
-  { path: '/docs/file2.pdf', data: buffer2 },
-  { path: '/docs/file3.pdf', data: buffer3 }
-];
-
-await Promise.all(
-  files.map(file => s3.uploadFile(file.path, file.data))
-);
-
-// Delete multiple files
-const filesToDelete = ['/old/file1.txt', '/old/file2.txt'];
-await Promise.all(
-  filesToDelete.map(path => s3.deleteFile(path))
-);
-```
 
 ## 📋 Complete Express.js Example
+# FULL DEMO PROJECT EXAMPLE:
+please see this project code before using: [aws-utils-demo github link!](https://github.com/hdriel/aws-utils-demo)
+![Main Screen - Preview](readme-assets/demo-bucket-image-preview.webp)
 
-```typescript
-import express from 'express';
-import { S3Util, ACLs } from '@hdriel/aws-utils';
-
-const app = express();
-const s3 = new S3Util({
-  bucket: process.env.S3_BUCKET!,
-  region: process.env.AWS_REGION,
-  accessKeyId: process.env.AWS_ACCESS_KEY_ID,
-  secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
-});
-
-// Initialize bucket on startup
-(async () => {
-  await s3.initBucket();
-  console.log('S3 bucket initialized');
-})();
-
-// Upload endpoint
-app.post('/api/upload',
-  s3.uploadSingleFile('file', '/uploads', {
-    maxFileSize: '10MB',
-    fileType: ['image', 'application'],
-    filename: async (req, file) => {
-      const timestamp = Date.now();
-      const sanitized = file.originalname.replace(/[^a-zA-Z0-9.-]/g, '_');
-      return `${timestamp}-${sanitized}`;
-    }
-  }),
-  async (req, res) => {
-    const { key, location, size } = req.s3File!;
-    
-    // Generate temporary URL
-    const url = await s3.fileUrl(key, '1h');
-    
-    res.json({ key, location, size, temporaryUrl: url });
-  }
-);
-
-// Download endpoint
-app.get('/api/download/:key(*)',
-  async (req, res, next) => {
-    const key = decodeURIComponent(req.params.key);
-    const ctrl = await s3.getStreamFileCtrl({ 
-      filePath: key,
-      forDownloading: true
-    });
-    ctrl(req, res, next);
-  }
-);
-
-// List files endpoint
-app.get('/api/files', async (req, res) => {
-  const { page = '0', size = '50' } = req.query;
-  
-  const result = await s3.directoryListPaginated('/uploads', {
-    pageNumber: parseInt(page as string),
-    pageSize: parseInt(size as string)
-  });
-  
-  res.json(result);
-});
-
-// Delete file endpoint
-app.delete('/api/files/:key(*)', async (req, res) => {
-  const key = decodeURIComponent(req.params.key);
-  await s3.deleteFile(key);
-  res.json({ success: true });
-});
-
-// Video streaming endpoint
-app.get('/api/video/:id',
-  async (req, res, next) => {
-    const videoPath = `/videos/${req.params.id}.mp4`;
-    const ctrl = await s3.getStreamVideoFileCtrl({
-      fileKey: videoPath,
-      contentType: 'video/mp4',
-      bufferMB: 5
-    });
-    ctrl(req, res, next);
-  }
-);
-
-app.listen(3000, () => {
-  console.log('Server running on port 3000');
-});
-```
-
-## 🚀 Performance Tips
-
-1. **Use Pagination**: For large directories, always use paginated methods
-2. **Stream Large Files**: Use streaming methods instead of loading entire files into memory
-3. **Connection Pooling**: The built-in connection pooling is optimized for concurrent requests
-4. **Batch Operations**: Use `Promise.all()` for parallel operations when possible
-5. **Presigned URLs**: Generate presigned URLs for direct client uploads/downloads when appropriate
-
-## 🛡️ Error Handling
-
-```typescript
-try {
-  await s3.uploadFile('/docs/file.pdf', buffer);
-} catch (error) {
-  if (error.name === 'NotFound' || error.$metadata?.httpStatusCode === 404) {
-    console.error('File not found');
-  } else {
-    console.error('Upload failed:', error);
-  }
-}
-```
 
 ## 📝 TypeScript Support
 
-This package is written in TypeScript and includes full type definitions:
-
-```typescript
-import type { 
-  ContentFile, 
-  FileUploadResponse,
-  TreeDirectoryItem,
-  UploadedS3File,
-  S3UploadOptions 
-} from '@hdriel/aws-utils';
-```
+This package is written in TypeScript and includes full type definitions
 
 ## 👤 Author
 

package/dist/index.cjs

@@ -271,7 +271,7 @@ var LambdaUtil = class {
 var import_client_s36 = require("@aws-sdk/client-s3");
 
 // src/aws/s3/s3-stream.ts
-var import_pathe = __toESM(require("pathe"), 1);
+var import_pathe2 = __toESM(require("pathe"), 1);
 var import_stream = require("stream");
 var import_util = require("util");
 var import_buffer2 = require("buffer");
@@ -295,6 +295,7 @@ var s3Limiter = (0, import_p_limit.default)(4);
 
 // src/utils/helpers.ts
 var import_bytes = __toESM(require("bytes"), 1);
+var import_ms = __toESM(require("ms"), 1);
 var parseRangeHeader = (range, contentLength, chunkSize) => {
   if (!range || !range.startsWith("bytes=")) return null;
   const rangeParts = range.replace("bytes=", "").split("-");
@@ -316,11 +317,16 @@ var getFileSize = (maxFileSize, defaultMaxFileSize) => {
   const fileSize = typeof fileSizeUnitValue === "number" ? fileSizeUnitValue : (0, import_bytes.default)(fileSizeUnitValue);
   return fileSize != null ? fileSize : void 0;
 };
+var getTotalSeconds = (msValue) => {
+  const value = (0, import_ms.default)(msValue);
+  return value / 1e3;
+};
 
 // src/aws/s3/s3-file.ts
 var import_buffer = require("buffer");
 var import_node_stream = require("stream");
-var import_ms = __toESM(require("ms"), 1);
+var import_ms2 = __toESM(require("ms"), 1);
+var import_pathe = require("pathe");
 var import_lib_storage = require("@aws-sdk/lib-storage");
 var import_s3_request_presigner = require("@aws-sdk/s3-request-presigner");
 var import_client_s34 = require("@aws-sdk/client-s3");
@@ -954,7 +960,13 @@ var S3File = class extends S3Directory {
       const normalizedKey = getNormalizedPath(filePath);
       if (!normalizedKey || normalizedKey === "/") throw new Error("No file key provided");
       const command = new import_client_s34.HeadObjectCommand({ Bucket: this.bucket, Key: normalizedKey });
-      return yield this.execute(command);
+      const result = yield this.execute(command);
+      if (!result) return result;
+      return __spreadProps(__spreadValues({}, result), {
+        Name: (0, import_pathe.basename)(normalizedKey),
+        Key: normalizedKey,
+        Location: `${this.link}${normalizedKey == null ? void 0 : normalizedKey.replace(/^\//, "")}`
+      });
     });
   }
   fileListInfo(directoryPath, fileNamePrefix) {
@@ -1080,7 +1092,7 @@ var S3File = class extends S3Directory {
       var _a2;
       let normalizedKey = getNormalizedPath(filePath);
       if (!normalizedKey || normalizedKey === "/") throw new Error("No file key provided");
-      const expiresInSeconds = typeof expiresIn === "number" ? expiresIn : (0, import_ms.default)(expiresIn) / 1e3;
+      const expiresInSeconds = typeof expiresIn === "number" ? expiresIn : (0, import_ms2.default)(expiresIn) / 1e3;
       const command = new import_client_s34.GetObjectCommand({ Bucket: this.bucket, Key: normalizedKey });
       const url = yield (0, import_s3_request_presigner.getSignedUrl)(this.s3Client, command, {
         expiresIn: expiresInSeconds
@@ -1216,22 +1228,20 @@ var S3Stream = class _S3Stream extends S3File {
     __publicField(this, "getImageFileViewCtrl", ({
       fileKey: _fileKey,
       queryField = "file",
-      cachingAge = 31536e3
+      paramField = "file",
+      cachingAgeSeconds = "1y"
     } = {}) => {
       return (req, res, next) => __async(this, null, function* () {
-        var _a2, _b, _c, _d, _e;
-        let fileKey = _fileKey || (((_a2 = req.query) == null ? void 0 : _a2[queryField]) ? decodeURIComponent((_b = req.query) == null ? void 0 : _b[queryField]) : void 0);
+        var _a2, _b, _c, _d, _e, _f;
+        let fileKey = _fileKey || (((_a2 = req.params) == null ? void 0 : _a2[paramField]) ? decodeURIComponent((_b = req.params) == null ? void 0 : _b[paramField]) : void 0) || (((_c = req.query) == null ? void 0 : _c[queryField]) ? decodeURIComponent((_d = req.query) == null ? void 0 : _d[queryField]) : void 0);
         if (!fileKey || fileKey === "/") {
-          (_d = this.logger) == null ? void 0 : _d.warn(req.id, "image file view required file query field", {
-            fileKey: (_c = req.query) == null ? void 0 : _c[queryField],
-            queryField
-          });
-          next("image file key is required");
+          (_e = this.logger) == null ? void 0 : _e.warn(req.id, "image fileKey is required");
+          next("image fileKey is required");
           return;
         }
         try {
           const imageBuffer = yield this.fileContent(fileKey, "buffer");
-          const ext = import_pathe.default.extname(fileKey).slice(1).toLowerCase();
+          const ext = import_pathe2.default.extname(fileKey).slice(1).toLowerCase();
           const mimeTypeMap = {
             jpg: "image/jpeg",
             jpeg: "image/jpeg",
@@ -1243,14 +1253,14 @@ var S3Stream = class _S3Stream extends S3File {
           };
           const contentType = mimeTypeMap[ext] || "application/octet-stream";
           res.setHeader("Content-Type", contentType);
-          if (cachingAge) res.setHeader("Cache-Control", `public, max-age=${cachingAge}`);
           res.setHeader("Content-Length", imageBuffer.length);
+          const cachingAge = !cachingAgeSeconds || typeof cachingAgeSeconds === "number" ? cachingAgeSeconds : getTotalSeconds(cachingAgeSeconds);
+          if (cachingAge) res.setHeader("Cache-Control", `public, max-age=${cachingAge}`);
           res.status(200).send(imageBuffer);
         } catch (error) {
-          (_e = this.logger) == null ? void 0 : _e.warn(req.id, "image view fileKey not found", {
-            fileKey,
-            localstack: this.localstack
-          });
+          (_f = this.logger) == null ? void 0 : _f.warn(req.id, "image fileKey not found", __spreadValues({
+            fileKey
+          }, this.localstack && { localstack: this.localstack }));
           next(`Failed to retrieve image file: ${error.message}`);
         }
       });
@@ -1259,18 +1269,20 @@ var S3Stream = class _S3Stream extends S3File {
     __publicField(this, "getPdfFileViewCtrl", ({
       fileKey: _fileKey,
       queryField = "file",
-      cachingAge = 31536e3
+      paramField = "file",
+      cachingAgeSeconds = "1y"
     } = {}) => {
       return (req, res, next) => __async(this, null, function* () {
-        var _a2, _b;
-        let fileKey = _fileKey || (((_a2 = req.query) == null ? void 0 : _a2[queryField]) ? decodeURIComponent((_b = req.query) == null ? void 0 : _b[queryField]) : void 0);
+        var _a2, _b, _c, _d, _e, _f;
+        let fileKey = _fileKey || (((_a2 = req.params) == null ? void 0 : _a2[paramField]) ? decodeURIComponent((_b = req.params) == null ? void 0 : _b[paramField]) : void 0) || (((_c = req.query) == null ? void 0 : _c[queryField]) ? decodeURIComponent((_d = req.query) == null ? void 0 : _d[queryField]) : void 0);
         if (!fileKey) {
-          next("pdf file key is required");
+          (_e = this.logger) == null ? void 0 : _e.warn(req.id, "pdf fileKey is required");
+          next("pdf fileKey is required");
           return;
         }
         try {
           const fileBuffer = yield this.fileContent(fileKey, "buffer");
-          const ext = import_pathe.default.extname(fileKey).slice(1).toLowerCase();
+          const ext = import_pathe2.default.extname(fileKey).slice(1).toLowerCase();
           const mimeTypeMap = {
             pdf: "application/pdf",
             txt: "text/plain",
@@ -1283,11 +1295,15 @@ var S3Stream = class _S3Stream extends S3File {
           };
           const contentType = mimeTypeMap[ext] || "application/octet-stream";
           res.setHeader("Content-Type", contentType);
-          res.setHeader("Content-Disposition", `inline; filename="${import_pathe.default.basename(fileKey)}"`);
-          res.setHeader("Cache-Control", `public, max-age=${cachingAge}`);
+          res.setHeader("Content-Disposition", `inline; filename="${import_pathe2.default.basename(fileKey)}"`);
           res.setHeader("Content-Length", fileBuffer.length);
+          const cachingAge = !cachingAgeSeconds || typeof cachingAgeSeconds === "number" ? cachingAgeSeconds : getTotalSeconds(cachingAgeSeconds);
+          res.setHeader("Cache-Control", `public, max-age=${cachingAge}`);
           res.status(200).send(fileBuffer);
         } catch (error) {
+          (_f = this.logger) == null ? void 0 : _f.warn(req.id, "pdf fileKey not found", __spreadValues({
+            fileKey
+          }, this.localstack && { localstack: this.localstack }));
           next(`Failed to retrieve pdf file: ${error.message}`);
         }
       });
@@ -1295,12 +1311,12 @@ var S3Stream = class _S3Stream extends S3File {
     this.maxUploadFileSizeRestriction = maxUploadFileSizeRestriction;
   }
   streamObjectFile(_0) {
-    return __async(this, arguments, function* (filePath, {
+    return __async(this, arguments, function* (fileKey, {
       Range,
       checkFileExists = true,
       abortSignal
     } = {}) {
-      let normalizedKey = getNormalizedPath(filePath);
+      let normalizedKey = getNormalizedPath(fileKey);
       if (!normalizedKey || normalizedKey === "/") throw new Error("No file key provided");
       if (checkFileExists) {
         const isExists = yield this.fileExists(normalizedKey);
@@ -1319,13 +1335,12 @@ var S3Stream = class _S3Stream extends S3File {
   }
   // todo: LOCALSTACK SANITY CHECKED - WORKING WELL, DON'T TOUCH!
   streamVideoFile(_0) {
-    return __async(this, arguments, function* ({
-      filePath,
+    return __async(this, arguments, function* (fileKey, {
       Range,
       abortSignal
-    }) {
+    } = {}) {
       var _a2;
-      let normalizedKey = getNormalizedPath(filePath);
+      let normalizedKey = getNormalizedPath(fileKey);
       if (!normalizedKey || normalizedKey === "/") throw new Error("No file key provided");
       try {
         const cmd = new import_client_s35.GetObjectCommand(__spreadValues({
@@ -1349,7 +1364,7 @@ var S3Stream = class _S3Stream extends S3File {
       } catch (error) {
         (_a2 = this.logger) == null ? void 0 : _a2.warn(this.reqId, "getS3VideoStream error", {
           Bucket: this.bucket,
-          filePath: normalizedKey,
+          fileKey: normalizedKey,
           Range,
           error
         });
@@ -1407,8 +1422,7 @@ var S3Stream = class _S3Stream extends S3File {
         const onClose = () => abort.abort();
         req.once("close", onClose);
         try {
-          const result = yield this.streamVideoFile({
-            filePath: normalizedKey,
+          const result = yield this.streamVideoFile(normalizedKey, {
             Range,
             abortSignal: abort.signal
           });
@@ -1473,11 +1487,10 @@ var S3Stream = class _S3Stream extends S3File {
   }
   // todo: LOCALSTACK SANITY CHECKED - WORKING WELL, DON'T TOUCH!
   getStreamFileCtrl(_0) {
-    return __async(this, arguments, function* ({
-      filePath,
+    return __async(this, arguments, function* (fileKey, {
       filename,
       forDownloading = false
-    }) {
+    } = {}) {
       return (req, res, next) => __async(this, null, function* () {
         var _a2, _b;
         const abort = new AbortController();
@@ -1488,7 +1501,7 @@ var S3Stream = class _S3Stream extends S3File {
           (_a3 = stream == null ? void 0 : stream.destroy) == null ? void 0 : _a3.call(stream);
         };
         req.once("close", onClose);
-        let normalizedKey = getNormalizedPath(filePath);
+        let normalizedKey = getNormalizedPath(fileKey);
         if (!normalizedKey || normalizedKey === "/") throw new Error("No file key provided");
         try {
           const isExists = yield this.fileExists(normalizedKey);
@@ -1517,7 +1530,7 @@ var S3Stream = class _S3Stream extends S3File {
           }
           stream.on("error", (err) => {
             var _a3, _b2;
-            (_a3 = this.logger) == null ? void 0 : _a3.warn(this.reqId, "Stream error", { filePath: normalizedKey, error: err });
+            (_a3 = this.logger) == null ? void 0 : _a3.warn(this.reqId, "Stream error", { fileKey: normalizedKey, error: err });
             abort.abort();
             (_b2 = stream == null ? void 0 : stream.destroy) == null ? void 0 : _b2.call(stream);
           });
@@ -1537,7 +1550,7 @@ var S3Stream = class _S3Stream extends S3File {
           if (isBenignStreamError) {
             return;
           }
-          (_b = this.logger) == null ? void 0 : _b.error(this.reqId, "Failed to stream file", { filePath: normalizedKey, error });
+          (_b = this.logger) == null ? void 0 : _b.error(this.reqId, "Failed to stream file", { fileKey: normalizedKey, error });
           if (!res.headersSent) {
             next(error);
           } else if (!res.writableEnded) {
@@ -1554,33 +1567,30 @@ var S3Stream = class _S3Stream extends S3File {
   }
   // todo: LOCALSTACK SANITY CHECKED - WORKING WELL, DON'T TOUCH!
   getStreamZipFileCtr(_0) {
-    return __async(this, arguments, function* ({
-      filePath,
+    return __async(this, arguments, function* (fileKey, {
       filename: _filename,
       compressionLevel = 5
-    }) {
+    } = {}) {
       return (req, res, next) => __async(this, null, function* () {
         var _a2, _b, _c, _d, _e;
-        const filePaths = [].concat(filePath).map((filePath2) => getNormalizedPath(filePath2)).filter((v) => v && v !== "/");
-        if (!filePaths.length) {
-          throw new Error("No file keys provided");
-        }
-        let filename = _filename || (/* @__PURE__ */ new Date()).toISOString();
-        filename = filename.endsWith(".zip") ? filename : `${filename}.zip`;
         const abort = new AbortController();
-        const onClose = () => {
-          abort.abort();
-        };
-        req.once("close", onClose);
+        const onClose = () => abort.abort();
         try {
-          (_a2 = this.logger) == null ? void 0 : _a2.info(this.reqId, "Starting parallel file download...", { fileCount: filePaths.length });
-          const downloadPromises = filePaths.map((filePath2) => __async(this, null, function* () {
+          const fileKeys = [].concat(fileKey).map((fileKey2) => getNormalizedPath(fileKey2)).filter((v) => v && v !== "/");
+          if (!fileKeys.length) {
+            throw new Error("No file keys provided");
+          }
+          let filename = _filename || (/* @__PURE__ */ new Date()).toISOString();
+          filename = filename.endsWith(".zip") ? filename : `${filename}.zip`;
+          req.once("close", onClose);
+          (_a2 = this.logger) == null ? void 0 : _a2.info(this.reqId, "Starting parallel file download...", { fileCount: fileKeys.length });
+          const downloadPromises = fileKeys.map((fileKey2) => __async(this, null, function* () {
             var _a3, _b2, _c2;
             try {
               if (abort.signal.aborted) return null;
-              const stream = yield this.streamObjectFile(filePath2, { abortSignal: abort.signal });
+              const stream = yield this.streamObjectFile(fileKey2, { abortSignal: abort.signal });
               if (!stream) {
-                (_a3 = this.logger) == null ? void 0 : _a3.warn(this.reqId, "File not found", { filePath: filePath2 });
+                (_a3 = this.logger) == null ? void 0 : _a3.warn(this.reqId, "File not found", { fileKey: fileKey2 });
                 return null;
               }
               const chunks = [];
@@ -1604,14 +1614,14 @@ var S3Stream = class _S3Stream extends S3File {
                 }
               }
               const buffer = import_buffer2.Buffer.concat(chunks);
-              const fileName = filePath2.split("/").pop() || filePath2;
+              const fileName = fileKey2.split("/").pop() || fileKey2;
               (_b2 = this.logger) == null ? void 0 : _b2.debug(this.reqId, "File downloaded", {
-                filePath: filePath2,
+                fileKey: fileKey2,
                 sizeMB: (buffer.length / (1024 * 1024)).toFixed(2)
               });
-              return { buffer, name: fileName, path: filePath2 };
+              return { buffer, name: fileName, path: fileKey2 };
             } catch (error2) {
-              (_c2 = this.logger) == null ? void 0 : _c2.warn(this.reqId, "Failed to download file", { filePath: filePath2, error: error2 });
+              (_c2 = this.logger) == null ? void 0 : _c2.warn(this.reqId, "Failed to download file", { fileKey: fileKey2, error: error2 });
               return null;
             }
           }));
@@ -1693,7 +1703,7 @@ var S3Stream = class _S3Stream extends S3File {
   static fileFilter(types, fileExt) {
     const fileTypesChecker = (fileExt == null ? void 0 : fileExt.length) ? new RegExp(`\\.(${fileExt.join("|")})$`, "i") : void 0;
     return function(_req, file, cb) {
-      const fileExtension = import_pathe.default.extname(file.originalname).substring(1);
+      const fileExtension = import_pathe2.default.extname(file.originalname).substring(1);
       const extname = fileTypesChecker ? fileTypesChecker.test(`.${fileExtension}`) : true;
       const mimeType = (types == null ? void 0 : types.length) ? types.some((type) => file.mimetype.startsWith(`${type}/`)) : true;
       if (mimeType && extname) {

package/dist/index.d.cts

@@ -242,7 +242,11 @@ declare class S3Directory extends S3Bucket {
 type S3FileProps = S3DirectoryProps;
 declare class S3File extends S3Directory {
     constructor(props: S3FileProps);
-    fileInfo(filePath: string): Promise<HeadObjectCommandOutput>;
+    fileInfo(filePath: string): Promise<HeadObjectCommandOutput & {
+        Name: string;
+        Location: string;
+        Key: string;
+    }>;
     fileListInfo(directoryPath?: string, fileNamePrefix?: string): Promise<(ContentFile & {
         Location: string;
     })[]>;
@@ -273,13 +277,12 @@ type S3StreamProps = S3FileProps & {
 declare class S3Stream extends S3File {
     private readonly maxUploadFileSizeRestriction;
     constructor({ maxUploadFileSizeRestriction, ...props }: S3StreamProps);
-    protected streamObjectFile(filePath: string, { Range, checkFileExists, abortSignal, }?: {
+    protected streamObjectFile(fileKey: string, { Range, checkFileExists, abortSignal, }?: {
         Range?: string;
         checkFileExists?: boolean;
         abortSignal?: AbortSignal;
     }): Promise<Readable | null>;
-    protected streamVideoFile({ filePath, Range, abortSignal, }: {
-        filePath: string;
+    protected streamVideoFile(fileKey: string, { Range, abortSignal, }?: {
         Range?: string;
         abortSignal?: AbortSignal;
     }): Promise<{
@@ -300,23 +303,23 @@ declare class S3Stream extends S3File {
         bufferMB?: number | undefined;
         streamTimeoutMS?: number | undefined;
     }): Promise<(req: Request$1 & any, res: Response & any, next: NextFunction & any) => Promise<any>>;
-    getImageFileViewCtrl: ({ fileKey: _fileKey, queryField, cachingAge, }?: {
+    getImageFileViewCtrl: ({ fileKey: _fileKey, queryField, paramField, cachingAgeSeconds, }?: {
         fileKey?: string;
         queryField?: string;
-        cachingAge?: number;
+        paramField?: string;
+        cachingAgeSeconds?: null | number | StringValue;
     }) => (req: Request$1 & any, res: Response & any, next: NextFunction & any) => Promise<void>;
-    getPdfFileViewCtrl: ({ fileKey: _fileKey, queryField, cachingAge, }?: {
+    getPdfFileViewCtrl: ({ fileKey: _fileKey, queryField, paramField, cachingAgeSeconds, }?: {
         fileKey?: string;
         queryField?: string;
-        cachingAge?: number;
+        paramField?: string;
+        cachingAgeSeconds?: null | number | StringValue;
     }) => (req: Request$1 & any, res: Response & any, next: NextFunction & any) => Promise<void>;
-    getStreamFileCtrl({ filePath, filename, forDownloading, }: {
-        filePath: string;
+    getStreamFileCtrl(fileKey: string, { filename, forDownloading, }?: {
         filename?: string;
         forDownloading?: boolean;
     }): Promise<(req: Request$1 & any, res: Response & any, next: NextFunction & any) => Promise<void>>;
-    getStreamZipFileCtr({ filePath, filename: _filename, compressionLevel, }: {
-        filePath: string | string[];
+    getStreamZipFileCtr(fileKey: string | string[], { filename: _filename, compressionLevel, }?: {
         filename?: string;
         compressionLevel?: number;
     }): Promise<(req: Request$1 & any, res: Response & any, next: NextFunction & any) => Promise<void>>;

package/dist/index.d.ts

@@ -242,7 +242,11 @@ declare class S3Directory extends S3Bucket {
 type S3FileProps = S3DirectoryProps;
 declare class S3File extends S3Directory {
     constructor(props: S3FileProps);
-    fileInfo(filePath: string): Promise<HeadObjectCommandOutput>;
+    fileInfo(filePath: string): Promise<HeadObjectCommandOutput & {
+        Name: string;
+        Location: string;
+        Key: string;
+    }>;
     fileListInfo(directoryPath?: string, fileNamePrefix?: string): Promise<(ContentFile & {
         Location: string;
     })[]>;
@@ -273,13 +277,12 @@ type S3StreamProps = S3FileProps & {
 declare class S3Stream extends S3File {
     private readonly maxUploadFileSizeRestriction;
     constructor({ maxUploadFileSizeRestriction, ...props }: S3StreamProps);
-    protected streamObjectFile(filePath: string, { Range, checkFileExists, abortSignal, }?: {
+    protected streamObjectFile(fileKey: string, { Range, checkFileExists, abortSignal, }?: {
         Range?: string;
         checkFileExists?: boolean;
         abortSignal?: AbortSignal;
     }): Promise<Readable | null>;
-    protected streamVideoFile({ filePath, Range, abortSignal, }: {
-        filePath: string;
+    protected streamVideoFile(fileKey: string, { Range, abortSignal, }?: {
         Range?: string;
         abortSignal?: AbortSignal;
     }): Promise<{
@@ -300,23 +303,23 @@ declare class S3Stream extends S3File {
         bufferMB?: number | undefined;
         streamTimeoutMS?: number | undefined;
     }): Promise<(req: Request$1 & any, res: Response & any, next: NextFunction & any) => Promise<any>>;
-    getImageFileViewCtrl: ({ fileKey: _fileKey, queryField, cachingAge, }?: {
+    getImageFileViewCtrl: ({ fileKey: _fileKey, queryField, paramField, cachingAgeSeconds, }?: {
         fileKey?: string;
         queryField?: string;
-        cachingAge?: number;
+        paramField?: string;
+        cachingAgeSeconds?: null | number | StringValue;
     }) => (req: Request$1 & any, res: Response & any, next: NextFunction & any) => Promise<void>;
-    getPdfFileViewCtrl: ({ fileKey: _fileKey, queryField, cachingAge, }?: {
+    getPdfFileViewCtrl: ({ fileKey: _fileKey, queryField, paramField, cachingAgeSeconds, }?: {
         fileKey?: string;
         queryField?: string;
-        cachingAge?: number;
+        paramField?: string;
+        cachingAgeSeconds?: null | number | StringValue;
     }) => (req: Request$1 & any, res: Response & any, next: NextFunction & any) => Promise<void>;
-    getStreamFileCtrl({ filePath, filename, forDownloading, }: {
-        filePath: string;
+    getStreamFileCtrl(fileKey: string, { filename, forDownloading, }?: {
         filename?: string;
         forDownloading?: boolean;
     }): Promise<(req: Request$1 & any, res: Response & any, next: NextFunction & any) => Promise<void>>;
-    getStreamZipFileCtr({ filePath, filename: _filename, compressionLevel, }: {
-        filePath: string | string[];
+    getStreamZipFileCtr(fileKey: string | string[], { filename: _filename, compressionLevel, }?: {
         filename?: string;
         compressionLevel?: number;
     }): Promise<(req: Request$1 & any, res: Response & any, next: NextFunction & any) => Promise<void>>;

package/dist/index.js

@@ -256,6 +256,7 @@ var s3Limiter = pLimit(4);
 
 // src/utils/helpers.ts
 import bytes from "bytes";
+import ms from "ms";
 var parseRangeHeader = (range, contentLength, chunkSize) => {
   if (!range || !range.startsWith("bytes=")) return null;
   const rangeParts = range.replace("bytes=", "").split("-");
@@ -277,11 +278,16 @@ var getFileSize = (maxFileSize, defaultMaxFileSize) => {
   const fileSize = typeof fileSizeUnitValue === "number" ? fileSizeUnitValue : bytes(fileSizeUnitValue);
   return fileSize != null ? fileSize : void 0;
 };
+var getTotalSeconds = (msValue) => {
+  const value = ms(msValue);
+  return value / 1e3;
+};
 
 // src/aws/s3/s3-file.ts
 import { Buffer as Buffer2 } from "buffer";
 import "stream";
-import ms from "ms";
+import ms2 from "ms";
+import { basename } from "pathe";
 import { Upload } from "@aws-sdk/lib-storage";
 import { getSignedUrl } from "@aws-sdk/s3-request-presigner";
 import {
@@ -943,7 +949,13 @@ var S3File = class extends S3Directory {
       const normalizedKey = getNormalizedPath(filePath);
       if (!normalizedKey || normalizedKey === "/") throw new Error("No file key provided");
       const command = new HeadObjectCommand2({ Bucket: this.bucket, Key: normalizedKey });
-      return yield this.execute(command);
+      const result = yield this.execute(command);
+      if (!result) return result;
+      return __spreadProps(__spreadValues({}, result), {
+        Name: basename(normalizedKey),
+        Key: normalizedKey,
+        Location: `${this.link}${normalizedKey == null ? void 0 : normalizedKey.replace(/^\//, "")}`
+      });
     });
   }
   fileListInfo(directoryPath, fileNamePrefix) {
@@ -1069,7 +1081,7 @@ var S3File = class extends S3Directory {
       var _a2;
       let normalizedKey = getNormalizedPath(filePath);
       if (!normalizedKey || normalizedKey === "/") throw new Error("No file key provided");
-      const expiresInSeconds = typeof expiresIn === "number" ? expiresIn : ms(expiresIn) / 1e3;
+      const expiresInSeconds = typeof expiresIn === "number" ? expiresIn : ms2(expiresIn) / 1e3;
       const command = new GetObjectCommand({ Bucket: this.bucket, Key: normalizedKey });
       const url = yield getSignedUrl(this.s3Client, command, {
         expiresIn: expiresInSeconds
@@ -1205,17 +1217,15 @@ var S3Stream = class _S3Stream extends S3File {
     __publicField(this, "getImageFileViewCtrl", ({
       fileKey: _fileKey,
       queryField = "file",
-      cachingAge = 31536e3
+      paramField = "file",
+      cachingAgeSeconds = "1y"
     } = {}) => {
       return (req, res, next) => __async(this, null, function* () {
-        var _a2, _b, _c, _d, _e;
-        let fileKey = _fileKey || (((_a2 = req.query) == null ? void 0 : _a2[queryField]) ? decodeURIComponent((_b = req.query) == null ? void 0 : _b[queryField]) : void 0);
+        var _a2, _b, _c, _d, _e, _f;
+        let fileKey = _fileKey || (((_a2 = req.params) == null ? void 0 : _a2[paramField]) ? decodeURIComponent((_b = req.params) == null ? void 0 : _b[paramField]) : void 0) || (((_c = req.query) == null ? void 0 : _c[queryField]) ? decodeURIComponent((_d = req.query) == null ? void 0 : _d[queryField]) : void 0);
         if (!fileKey || fileKey === "/") {
-          (_d = this.logger) == null ? void 0 : _d.warn(req.id, "image file view required file query field", {
-            fileKey: (_c = req.query) == null ? void 0 : _c[queryField],
-            queryField
-          });
-          next("image file key is required");
+          (_e = this.logger) == null ? void 0 : _e.warn(req.id, "image fileKey is required");
+          next("image fileKey is required");
           return;
         }
         try {
@@ -1232,14 +1242,14 @@ var S3Stream = class _S3Stream extends S3File {
           };
           const contentType = mimeTypeMap[ext] || "application/octet-stream";
           res.setHeader("Content-Type", contentType);
-          if (cachingAge) res.setHeader("Cache-Control", `public, max-age=${cachingAge}`);
           res.setHeader("Content-Length", imageBuffer.length);
+          const cachingAge = !cachingAgeSeconds || typeof cachingAgeSeconds === "number" ? cachingAgeSeconds : getTotalSeconds(cachingAgeSeconds);
+          if (cachingAge) res.setHeader("Cache-Control", `public, max-age=${cachingAge}`);
           res.status(200).send(imageBuffer);
         } catch (error) {
-          (_e = this.logger) == null ? void 0 : _e.warn(req.id, "image view fileKey not found", {
-            fileKey,
-            localstack: this.localstack
-          });
+          (_f = this.logger) == null ? void 0 : _f.warn(req.id, "image fileKey not found", __spreadValues({
+            fileKey
+          }, this.localstack && { localstack: this.localstack }));
           next(`Failed to retrieve image file: ${error.message}`);
         }
       });
@@ -1248,13 +1258,15 @@ var S3Stream = class _S3Stream extends S3File {
     __publicField(this, "getPdfFileViewCtrl", ({
       fileKey: _fileKey,
       queryField = "file",
-      cachingAge = 31536e3
+      paramField = "file",
+      cachingAgeSeconds = "1y"
     } = {}) => {
       return (req, res, next) => __async(this, null, function* () {
-        var _a2, _b;
-        let fileKey = _fileKey || (((_a2 = req.query) == null ? void 0 : _a2[queryField]) ? decodeURIComponent((_b = req.query) == null ? void 0 : _b[queryField]) : void 0);
+        var _a2, _b, _c, _d, _e, _f;
+        let fileKey = _fileKey || (((_a2 = req.params) == null ? void 0 : _a2[paramField]) ? decodeURIComponent((_b = req.params) == null ? void 0 : _b[paramField]) : void 0) || (((_c = req.query) == null ? void 0 : _c[queryField]) ? decodeURIComponent((_d = req.query) == null ? void 0 : _d[queryField]) : void 0);
         if (!fileKey) {
-          next("pdf file key is required");
+          (_e = this.logger) == null ? void 0 : _e.warn(req.id, "pdf fileKey is required");
+          next("pdf fileKey is required");
           return;
         }
         try {
@@ -1273,10 +1285,14 @@ var S3Stream = class _S3Stream extends S3File {
           const contentType = mimeTypeMap[ext] || "application/octet-stream";
           res.setHeader("Content-Type", contentType);
           res.setHeader("Content-Disposition", `inline; filename="${path.basename(fileKey)}"`);
-          res.setHeader("Cache-Control", `public, max-age=${cachingAge}`);
           res.setHeader("Content-Length", fileBuffer.length);
+          const cachingAge = !cachingAgeSeconds || typeof cachingAgeSeconds === "number" ? cachingAgeSeconds : getTotalSeconds(cachingAgeSeconds);
+          res.setHeader("Cache-Control", `public, max-age=${cachingAge}`);
           res.status(200).send(fileBuffer);
         } catch (error) {
+          (_f = this.logger) == null ? void 0 : _f.warn(req.id, "pdf fileKey not found", __spreadValues({
+            fileKey
+          }, this.localstack && { localstack: this.localstack }));
           next(`Failed to retrieve pdf file: ${error.message}`);
         }
       });
@@ -1284,12 +1300,12 @@ var S3Stream = class _S3Stream extends S3File {
     this.maxUploadFileSizeRestriction = maxUploadFileSizeRestriction;
   }
   streamObjectFile(_0) {
-    return __async(this, arguments, function* (filePath, {
+    return __async(this, arguments, function* (fileKey, {
       Range,
       checkFileExists = true,
       abortSignal
     } = {}) {
-      let normalizedKey = getNormalizedPath(filePath);
+      let normalizedKey = getNormalizedPath(fileKey);
       if (!normalizedKey || normalizedKey === "/") throw new Error("No file key provided");
       if (checkFileExists) {
         const isExists = yield this.fileExists(normalizedKey);
@@ -1308,13 +1324,12 @@ var S3Stream = class _S3Stream extends S3File {
   }
   // todo: LOCALSTACK SANITY CHECKED - WORKING WELL, DON'T TOUCH!
   streamVideoFile(_0) {
-    return __async(this, arguments, function* ({
-      filePath,
+    return __async(this, arguments, function* (fileKey, {
       Range,
       abortSignal
-    }) {
+    } = {}) {
       var _a2;
-      let normalizedKey = getNormalizedPath(filePath);
+      let normalizedKey = getNormalizedPath(fileKey);
       if (!normalizedKey || normalizedKey === "/") throw new Error("No file key provided");
       try {
         const cmd = new GetObjectCommand2(__spreadValues({
@@ -1338,7 +1353,7 @@ var S3Stream = class _S3Stream extends S3File {
       } catch (error) {
         (_a2 = this.logger) == null ? void 0 : _a2.warn(this.reqId, "getS3VideoStream error", {
           Bucket: this.bucket,
-          filePath: normalizedKey,
+          fileKey: normalizedKey,
           Range,
           error
         });
@@ -1396,8 +1411,7 @@ var S3Stream = class _S3Stream extends S3File {
         const onClose = () => abort.abort();
         req.once("close", onClose);
         try {
-          const result = yield this.streamVideoFile({
-            filePath: normalizedKey,
+          const result = yield this.streamVideoFile(normalizedKey, {
             Range,
             abortSignal: abort.signal
           });
@@ -1462,11 +1476,10 @@ var S3Stream = class _S3Stream extends S3File {
   }
   // todo: LOCALSTACK SANITY CHECKED - WORKING WELL, DON'T TOUCH!
   getStreamFileCtrl(_0) {
-    return __async(this, arguments, function* ({
-      filePath,
+    return __async(this, arguments, function* (fileKey, {
       filename,
       forDownloading = false
-    }) {
+    } = {}) {
       return (req, res, next) => __async(this, null, function* () {
         var _a2, _b;
         const abort = new AbortController();
@@ -1477,7 +1490,7 @@ var S3Stream = class _S3Stream extends S3File {
           (_a3 = stream == null ? void 0 : stream.destroy) == null ? void 0 : _a3.call(stream);
         };
         req.once("close", onClose);
-        let normalizedKey = getNormalizedPath(filePath);
+        let normalizedKey = getNormalizedPath(fileKey);
         if (!normalizedKey || normalizedKey === "/") throw new Error("No file key provided");
         try {
           const isExists = yield this.fileExists(normalizedKey);
@@ -1506,7 +1519,7 @@ var S3Stream = class _S3Stream extends S3File {
           }
           stream.on("error", (err) => {
             var _a3, _b2;
-            (_a3 = this.logger) == null ? void 0 : _a3.warn(this.reqId, "Stream error", { filePath: normalizedKey, error: err });
+            (_a3 = this.logger) == null ? void 0 : _a3.warn(this.reqId, "Stream error", { fileKey: normalizedKey, error: err });
             abort.abort();
             (_b2 = stream == null ? void 0 : stream.destroy) == null ? void 0 : _b2.call(stream);
           });
@@ -1526,7 +1539,7 @@ var S3Stream = class _S3Stream extends S3File {
           if (isBenignStreamError) {
             return;
           }
-          (_b = this.logger) == null ? void 0 : _b.error(this.reqId, "Failed to stream file", { filePath: normalizedKey, error });
+          (_b = this.logger) == null ? void 0 : _b.error(this.reqId, "Failed to stream file", { fileKey: normalizedKey, error });
           if (!res.headersSent) {
             next(error);
           } else if (!res.writableEnded) {
@@ -1543,33 +1556,30 @@ var S3Stream = class _S3Stream extends S3File {
   }
   // todo: LOCALSTACK SANITY CHECKED - WORKING WELL, DON'T TOUCH!
   getStreamZipFileCtr(_0) {
-    return __async(this, arguments, function* ({
-      filePath,
+    return __async(this, arguments, function* (fileKey, {
       filename: _filename,
       compressionLevel = 5
-    }) {
+    } = {}) {
       return (req, res, next) => __async(this, null, function* () {
         var _a2, _b, _c, _d, _e;
-        const filePaths = [].concat(filePath).map((filePath2) => getNormalizedPath(filePath2)).filter((v) => v && v !== "/");
-        if (!filePaths.length) {
-          throw new Error("No file keys provided");
-        }
-        let filename = _filename || (/* @__PURE__ */ new Date()).toISOString();
-        filename = filename.endsWith(".zip") ? filename : `${filename}.zip`;
         const abort = new AbortController();
-        const onClose = () => {
-          abort.abort();
-        };
-        req.once("close", onClose);
+        const onClose = () => abort.abort();
         try {
-          (_a2 = this.logger) == null ? void 0 : _a2.info(this.reqId, "Starting parallel file download...", { fileCount: filePaths.length });
-          const downloadPromises = filePaths.map((filePath2) => __async(this, null, function* () {
+          const fileKeys = [].concat(fileKey).map((fileKey2) => getNormalizedPath(fileKey2)).filter((v) => v && v !== "/");
+          if (!fileKeys.length) {
+            throw new Error("No file keys provided");
+          }
+          let filename = _filename || (/* @__PURE__ */ new Date()).toISOString();
+          filename = filename.endsWith(".zip") ? filename : `${filename}.zip`;
+          req.once("close", onClose);
+          (_a2 = this.logger) == null ? void 0 : _a2.info(this.reqId, "Starting parallel file download...", { fileCount: fileKeys.length });
+          const downloadPromises = fileKeys.map((fileKey2) => __async(this, null, function* () {
             var _a3, _b2, _c2;
             try {
               if (abort.signal.aborted) return null;
-              const stream = yield this.streamObjectFile(filePath2, { abortSignal: abort.signal });
+              const stream = yield this.streamObjectFile(fileKey2, { abortSignal: abort.signal });
               if (!stream) {
-                (_a3 = this.logger) == null ? void 0 : _a3.warn(this.reqId, "File not found", { filePath: filePath2 });
+                (_a3 = this.logger) == null ? void 0 : _a3.warn(this.reqId, "File not found", { fileKey: fileKey2 });
                 return null;
               }
               const chunks = [];
@@ -1593,14 +1603,14 @@ var S3Stream = class _S3Stream extends S3File {
                 }
               }
               const buffer = Buffer3.concat(chunks);
-              const fileName = filePath2.split("/").pop() || filePath2;
+              const fileName = fileKey2.split("/").pop() || fileKey2;
               (_b2 = this.logger) == null ? void 0 : _b2.debug(this.reqId, "File downloaded", {
-                filePath: filePath2,
+                fileKey: fileKey2,
                 sizeMB: (buffer.length / (1024 * 1024)).toFixed(2)
               });
-              return { buffer, name: fileName, path: filePath2 };
+              return { buffer, name: fileName, path: fileKey2 };
             } catch (error2) {
-              (_c2 = this.logger) == null ? void 0 : _c2.warn(this.reqId, "Failed to download file", { filePath: filePath2, error: error2 });
+              (_c2 = this.logger) == null ? void 0 : _c2.warn(this.reqId, "Failed to download file", { fileKey: fileKey2, error: error2 });
               return null;
             }
           }));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hdriel/aws-utils",
-  "version": "1.1.3",
+  "version": "1.1.5",
   "description": "Simplified AWS SDK (v3) utilities for S3 (upload, download, streaming) with TypeScript support",
   "author": "Hadriel Benjo (https://github.com/hdriel)",
   "type": "module",