@hdriel/aws-utils 1.0.2 → 1.0.3

package/dist/index.cjs

@@ -298,6 +298,7 @@ var parseRangeHeader = (range, contentLength, chunkSize) => {
   }
   return [start, Math.min(end, end)];
 };
+var getNormalizedPath = (directoryPath) => decodeURIComponent((directoryPath == null ? void 0 : directoryPath.replace(/^\/+/, "").replace(/\/+$/, "")) || "");
 var S3BucketUtil = class _S3BucketUtil {
   constructor({
     logger: logger2,
@@ -606,7 +607,7 @@ var S3BucketUtil = class _S3BucketUtil {
   // ##### DIRECTORY BLOCK ##########################
   createDirectory(directoryPath) {
     return __async(this, null, function* () {
-      let normalizedPath = decodeURIComponent((directoryPath == null ? void 0 : directoryPath.replace(/^\//, "").replace(/\/$/, "")) || "");
+      let normalizedPath = getNormalizedPath(directoryPath);
       if (!normalizedPath) throw new Error("No directory path provided");
       if (normalizedPath === "/") normalizedPath = "";
       const command = new import_client_s3.PutObjectCommand({ Bucket: this.bucket, Key: `${normalizedPath}/` });
@@ -617,10 +618,8 @@ var S3BucketUtil = class _S3BucketUtil {
   deleteDirectory(directoryPath) {
     return __async(this, null, function* () {
       var _a2, _b, _c, _d, _e, _f, _g;
-      let normalizedPath = decodeURIComponent((directoryPath == null ? void 0 : directoryPath.replace(/^\//, "").replace(/\/$/, "")) || "");
-      if (!normalizedPath) {
-        throw new Error("No directory path provided");
-      }
+      let normalizedPath = getNormalizedPath(directoryPath);
+      if (!normalizedPath) throw new Error("No directory path provided");
       if (normalizedPath === "/") normalizedPath = "";
       let totalDeletedCount = 0;
       let ContinuationToken = void 0;
@@ -687,8 +686,8 @@ var S3BucketUtil = class _S3BucketUtil {
   }
   directoryList(directoryPath) {
     return __async(this, null, function* () {
-      let normalizedPath = decodeURIComponent((directoryPath == null ? void 0 : directoryPath.replace(/^\//, "").replace(/\/$/, "")) || "");
-      if (directoryPath !== "/" && directoryPath !== "" && directoryPath !== void 0) normalizedPath += "/";
+      let normalizedPath = getNormalizedPath(directoryPath);
+      if (normalizedPath !== "/" && directoryPath !== "" && directoryPath !== void 0) normalizedPath += "/";
       else normalizedPath = "";
       const result = yield this.execute(
         new import_client_s3.ListObjectsV2Command({
@@ -712,14 +711,63 @@ var S3BucketUtil = class _S3BucketUtil {
       return { directories, files };
     });
   }
+  directoryListPaginated(_0) {
+    return __async(this, arguments, function* (directoryPath, {
+      pageSize = 100,
+      pageNumber = 0
+      // 0-based: page 0 = items 0-99, page 1 = items 100-199, page 2 = items 200-299
+    } = {}) {
+      let normalizedPath = getNormalizedPath(directoryPath);
+      if (normalizedPath !== "/" && directoryPath !== "" && directoryPath !== void 0) normalizedPath += "/";
+      else normalizedPath = "";
+      let continuationToken = void 0;
+      let currentPage = 0;
+      let allDirectories = [];
+      let allFiles = [];
+      while (currentPage <= pageNumber) {
+        const result = yield this.execute(
+          new import_client_s3.ListObjectsV2Command({
+            Bucket: this.bucket,
+            Prefix: normalizedPath,
+            Delimiter: "/",
+            MaxKeys: pageSize,
+            ContinuationToken: continuationToken
+          })
+        );
+        if (currentPage === pageNumber) {
+          allDirectories = (result.CommonPrefixes || []).map((prefix) => prefix.Prefix).map((prefix) => {
+            const relativePath = prefix.replace(normalizedPath, "");
+            return relativePath.replace(/\/$/, "");
+          }).filter((dir) => dir);
+          allFiles = (result.Contents || []).filter((content) => {
+            var _a2;
+            return content.Key !== normalizedPath && !((_a2 = content.Key) == null ? void 0 : _a2.endsWith("/"));
+          }).map((content) => __spreadProps(__spreadValues({}, content), {
+            Name: content.Key.replace(normalizedPath, "") || content.Key,
+            LastModified: new Date(content.LastModified)
+          }));
+        }
+        continuationToken = result.NextContinuationToken;
+        if (!result.IsTruncated || !continuationToken) {
+          break;
+        }
+        currentPage++;
+      }
+      return {
+        directories: allDirectories,
+        files: allFiles,
+        totalFetched: allFiles.length + allDirectories.length
+      };
+    });
+  }
   /**
    * Get all files recursively (example for search/indexing)
    * @param directoryPath
    */
   directoryListRecursive(directoryPath) {
     return __async(this, null, function* () {
-      let normalizedPath = decodeURIComponent((directoryPath == null ? void 0 : directoryPath.replace(/^\//, "").replace(/\/$/, "")) || "");
-      if (directoryPath !== "/" && directoryPath !== "" && directoryPath !== void 0) normalizedPath += "/";
+      let normalizedPath = getNormalizedPath(directoryPath);
+      if (normalizedPath !== "/" && directoryPath !== "" && directoryPath !== void 0) normalizedPath += "/";
       else normalizedPath = "";
       const allDirectories = [];
       const allFiles = [];
@@ -783,7 +831,7 @@ var S3BucketUtil = class _S3BucketUtil {
    */
   directoryTree(directoryPath) {
     return __async(this, null, function* () {
-      let normalizedPath = decodeURIComponent((directoryPath == null ? void 0 : directoryPath.replace(/^\//, "").replace(/\/$/, "")) || "");
+      let normalizedPath = getNormalizedPath(directoryPath);
       const lastDirectory = directoryPath == null ? void 0 : directoryPath.split("/").pop();
       const { directories, files } = yield this.directoryList(normalizedPath);
       if (directoryPath !== "/" && directoryPath !== "" && directoryPath !== void 0) normalizedPath += "/";
@@ -814,7 +862,7 @@ var S3BucketUtil = class _S3BucketUtil {
   // ##### FILES BLOCK ##########################
   fileInfo(filePath) {
     return __async(this, null, function* () {
-      const normalizedKey = decodeURIComponent((filePath == null ? void 0 : filePath.replace(/^\//, "").replace(/\/$/, "")) || "");
+      const normalizedKey = getNormalizedPath(filePath);
       if (!normalizedKey || normalizedKey === "/") {
         throw new Error("No file key provided");
       }
@@ -825,8 +873,8 @@ var S3BucketUtil = class _S3BucketUtil {
   fileListInfo(directoryPath, fileNamePrefix) {
     return __async(this, null, function* () {
       var _a2, _b;
-      let normalizedPath = decodeURIComponent((directoryPath == null ? void 0 : directoryPath.replace(/^\//, "").replace(/\/$/, "")) || "");
-      if (directoryPath !== "/" && directoryPath !== "" && directoryPath !== void 0) normalizedPath += "/";
+      let normalizedPath = getNormalizedPath(directoryPath);
+      if (normalizedPath !== "/" && directoryPath !== "" && directoryPath !== void 0) normalizedPath += "/";
       else normalizedPath = "";
       const prefix = normalizedPath + (fileNamePrefix || "");
       const command = new import_client_s3.ListObjectsCommand({
@@ -848,13 +896,65 @@ var S3BucketUtil = class _S3BucketUtil {
       return files;
     });
   }
+  fileListInfoPaginated(_0) {
+    return __async(this, arguments, function* (directoryPath, {
+      fileNamePrefix,
+      pageNumber = 0,
+      // 0-based: page 0 = items 0-99, page 1 = items 100-199, page 2 = items 200-299
+      pageSize = 100
+    } = {}) {
+      var _a2, _b;
+      let normalizedPath = getNormalizedPath(directoryPath);
+      if (normalizedPath !== "/" && directoryPath !== "" && directoryPath !== void 0) normalizedPath += "/";
+      else normalizedPath = "";
+      const prefix = normalizedPath + (fileNamePrefix || "");
+      let continuationToken;
+      let currentPage = 0;
+      let resultFiles = [];
+      while (currentPage <= pageNumber) {
+        const result = yield this.execute(
+          new import_client_s3.ListObjectsV2Command({
+            Bucket: this.bucket,
+            Prefix: prefix,
+            Delimiter: "/",
+            MaxKeys: pageSize,
+            ContinuationToken: continuationToken
+          })
+        );
+        if (currentPage === pageNumber) {
+          resultFiles = ((_a2 = result.Contents) != null ? _a2 : []).filter((v) => v).map(
+            (content) => {
+              var _a3, _b2;
+              return __spreadProps(__spreadValues({}, content), {
+                Name: (_b2 = (_a3 = content.Key) == null ? void 0 : _a3.replace(prefix, "")) != null ? _b2 : content.Key,
+                LastModified: content.LastModified ? new Date(content.LastModified) : null
+              });
+            }
+          ).filter((content) => content.Name);
+        }
+        continuationToken = result.NextContinuationToken;
+        if (!result.IsTruncated || !continuationToken) {
+          break;
+        }
+        currentPage++;
+      }
+      (_b = this.logger) == null ? void 0 : _b.debug(null, "file list info paginated", {
+        prefix,
+        pageNumber,
+        pageSize,
+        fileCount: resultFiles.length
+      });
+      return {
+        files: resultFiles,
+        totalFetched: resultFiles.length
+      };
+    });
+  }
   taggingFile(filePath, tagVersion = "1.0.0") {
     return __async(this, null, function* () {
       try {
-        const normalizedKey = decodeURIComponent((filePath == null ? void 0 : filePath.replace(/^\//, "").replace(/\/$/, "")) || "");
-        if (!normalizedKey || normalizedKey === "/") {
-          throw new Error("No file key provided");
-        }
+        const normalizedKey = getNormalizedPath(filePath);
+        if (!normalizedKey || normalizedKey === "/") throw new Error("No file key provided");
         const command = new import_client_s3.PutObjectTaggingCommand({
           Bucket: this.bucket,
           Key: normalizedKey,
@@ -870,10 +970,8 @@ var S3BucketUtil = class _S3BucketUtil {
   fileVersion(filePath) {
     return __async(this, null, function* () {
       var _a2, _b;
-      const normalizedKey = decodeURIComponent((filePath == null ? void 0 : filePath.replace(/^\//, "").replace(/\/$/, "")) || "");
-      if (!normalizedKey || normalizedKey === "/") {
-        throw new Error("No file key provided");
-      }
+      const normalizedKey = getNormalizedPath(filePath);
+      if (!normalizedKey || normalizedKey === "/") throw new Error("No file key provided");
       const command = new import_client_s3.GetObjectTaggingCommand({ Bucket: this.bucket, Key: normalizedKey });
       const result = yield this.execute(command);
       const tag = (_a2 = result.TagSet) == null ? void 0 : _a2.find((tag2) => tag2.Key === "version");
@@ -883,10 +981,8 @@ var S3BucketUtil = class _S3BucketUtil {
   fileUrl(filePath, expiresIn = "15m") {
     return __async(this, null, function* () {
       var _a2;
-      const normalizedKey = decodeURIComponent((filePath == null ? void 0 : filePath.replace(/^\//, "").replace(/\/$/, "")) || "");
-      if (!normalizedKey || normalizedKey === "/") {
-        throw new Error("No file key provided");
-      }
+      const 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 command = new import_client_s3.GetObjectCommand({ Bucket: this.bucket, Key: normalizedKey });
       const url = yield (0, import_s3_request_presigner.getSignedUrl)(this.s3Client, command, {
@@ -900,10 +996,8 @@ var S3BucketUtil = class _S3BucketUtil {
   sizeOf(filePath, unit = "bytes") {
     return __async(this, null, function* () {
       var _a2, _b, _c;
-      const normalizedKey = decodeURIComponent((filePath == null ? void 0 : filePath.replace(/^\//, "").replace(/\/$/, "")) || "");
-      if (!normalizedKey || normalizedKey === "/") {
-        throw new Error("No file key provided");
-      }
+      const normalizedKey = getNormalizedPath(filePath);
+      if (!normalizedKey || normalizedKey === "/") throw new Error("No file key provided");
       try {
         const command = new import_client_s3.HeadObjectCommand({ Bucket: this.bucket, Key: normalizedKey });
         const headObject = yield this.execute(command);
@@ -931,10 +1025,8 @@ var S3BucketUtil = class _S3BucketUtil {
     return __async(this, null, function* () {
       var _a2;
       try {
-        const normalizedKey = decodeURIComponent((filePath == null ? void 0 : filePath.replace(/^\//, "").replace(/\/$/, "")) || "");
-        if (!normalizedKey || normalizedKey === "/") {
-          throw new Error("No file key provided");
-        }
+        const normalizedKey = getNormalizedPath(filePath);
+        if (!normalizedKey || normalizedKey === "/") throw new Error("No file key provided");
         const command = new import_client_s3.HeadObjectCommand({ Bucket: this.bucket, Key: normalizedKey });
         yield this.execute(command);
         return true;
@@ -948,10 +1040,8 @@ var S3BucketUtil = class _S3BucketUtil {
   }
   fileContent(filePath, format = "buffer") {
     return __async(this, null, function* () {
-      const normalizedKey = decodeURIComponent((filePath == null ? void 0 : filePath.replace(/^\//, "").replace(/\/$/, "")) || "");
-      if (!normalizedKey || normalizedKey === "/") {
-        throw new Error("No file key provided");
-      }
+      const normalizedKey = getNormalizedPath(filePath);
+      if (!normalizedKey || normalizedKey === "/") throw new Error("No file key provided");
       const command = new import_client_s3.GetObjectCommand({ Bucket: this.bucket, Key: normalizedKey });
       const result = yield this.execute(command);
       if (!result.Body) {
@@ -983,10 +1073,8 @@ var S3BucketUtil = class _S3BucketUtil {
   }
   uploadFile(_0, _1) {
     return __async(this, arguments, function* (filePath, fileData, acl = "private" /* private */, version = "1.0.0") {
-      const normalizedKey = decodeURIComponent((filePath == null ? void 0 : filePath.replace(/^\//, "").replace(/\/$/, "")) || "");
-      if (!normalizedKey || normalizedKey === "/") {
-        throw new Error("No file key provided");
-      }
+      const normalizedKey = getNormalizedPath(filePath);
+      if (!normalizedKey || normalizedKey === "/") throw new Error("No file key provided");
       const upload = new import_lib_storage.Upload({
         client: this.s3Client,
         params: {
@@ -1008,10 +1096,8 @@ var S3BucketUtil = class _S3BucketUtil {
   }
   deleteFile(filePath) {
     return __async(this, null, function* () {
-      const normalizedKey = decodeURIComponent((filePath == null ? void 0 : filePath.replace(/^\//, "").replace(/\/$/, "")) || "");
-      if (!normalizedKey || normalizedKey === "/") {
-        throw new Error("No file key provided");
-      }
+      const normalizedKey = getNormalizedPath(filePath);
+      if (!normalizedKey || normalizedKey === "/") throw new Error("No file key provided");
       const command = new import_client_s3.DeleteObjectCommand({ Bucket: this.bucket, Key: normalizedKey });
       return yield this.execute(command);
     });
@@ -1023,10 +1109,8 @@ var S3BucketUtil = class _S3BucketUtil {
       checkFileExists = true,
       abortSignal
     } = {}) {
-      const normalizedKey = decodeURIComponent((filePath == null ? void 0 : filePath.replace(/^\//, "").replace(/\/$/, "")) || "");
-      if (!normalizedKey || normalizedKey === "/") {
-        throw new Error("No file key provided");
-      }
+      const normalizedKey = getNormalizedPath(filePath);
+      if (!normalizedKey || normalizedKey === "/") throw new Error("No file key provided");
       if (checkFileExists) {
         const isExists = yield this.fileExists(normalizedKey);
         if (!isExists) return null;
@@ -1049,10 +1133,8 @@ var S3BucketUtil = class _S3BucketUtil {
       abortSignal
     }) {
       var _a2;
-      const normalizedKey = decodeURIComponent((filePath == null ? void 0 : filePath.replace(/^\//, "").replace(/\/$/, "")) || "");
-      if (!normalizedKey || normalizedKey === "/") {
-        throw new Error("No file key provided");
-      }
+      const normalizedKey = getNormalizedPath(filePath);
+      if (!normalizedKey || normalizedKey === "/") throw new Error("No file key provided");
       try {
         const cmd = new import_client_s3.GetObjectCommand(__spreadValues({
           Bucket: this.bucket,
@@ -1091,9 +1173,7 @@ var S3BucketUtil = class _S3BucketUtil {
     }) {
       return (req, res, next) => __async(this, null, function* () {
         var _a2, _b, _c, _d, _e;
-        const filePaths = [].concat(filePath).map((filePath2) => {
-          return decodeURIComponent((filePath2 == null ? void 0 : filePath2.replace(/^\//, "").replace(/\/$/, "")) || "");
-        }).filter((v) => v && v !== "/");
+        const filePaths = [].concat(filePath).map((filePath2) => getNormalizedPath(filePath2)).filter((v) => v && v !== "/");
         if (!filePaths.length) {
           throw new Error("No file keys provided");
         }
@@ -1234,10 +1314,8 @@ var S3BucketUtil = class _S3BucketUtil {
           (_a3 = stream == null ? void 0 : stream.destroy) == null ? void 0 : _a3.call(stream);
         };
         req.once("close", onClose);
-        const normalizedKey = decodeURIComponent((filePath == null ? void 0 : filePath.replace(/^\//, "").replace(/\/$/, "")) || "");
-        if (!normalizedKey || normalizedKey === "/") {
-          throw new Error("No file key provided");
-        }
+        const normalizedKey = getNormalizedPath(filePath);
+        if (!normalizedKey || normalizedKey === "/") throw new Error("No file key provided");
         try {
           const isExists = yield this.fileExists(normalizedKey);
           if (!isExists) {
@@ -1308,10 +1386,8 @@ var S3BucketUtil = class _S3BucketUtil {
     }) {
       return (req, res, next) => __async(this, null, function* () {
         var _a2, _b, _c, _d, _e, _f;
-        const normalizedKey = decodeURIComponent((fileKey == null ? void 0 : fileKey.replace(/^\//, "").replace(/\/$/, "")) || "");
-        if (!normalizedKey || normalizedKey === "/") {
-          throw new Error("No file key provided");
-        }
+        const normalizedKey = getNormalizedPath(fileKey);
+        if (!normalizedKey || normalizedKey === "/") throw new Error("No file key provided");
         const isExists = yield this.fileExists(normalizedKey);
         const fileSize = yield this.sizeOf(normalizedKey);
         let Range;
@@ -1439,7 +1515,7 @@ var S3BucketUtil = class _S3BucketUtil {
     }
     return fileSize;
   }
-  getUploadFileMW(directory, {
+  getUploadFileMW(directoryPath, {
     acl = "private" /* private */,
     maxFileSize,
     filename: _filename,
@@ -1447,8 +1523,8 @@ var S3BucketUtil = class _S3BucketUtil {
     fileExt = [],
     metadata: customMetadata
   } = {}) {
-    let normalizedPath = decodeURIComponent((directory == null ? void 0 : directory.replace(/^\//, "").replace(/\/$/, "")) || "");
-    if (directory !== "/" && directory !== "" && directory !== void 0) normalizedPath += "/";
+    let normalizedPath = getNormalizedPath(directoryPath);
+    if (normalizedPath !== "/" && directoryPath !== "" && directoryPath !== void 0) normalizedPath += "/";
     else normalizedPath = "";
     const fileSize = this.getFileSize(maxFileSize);
     const fileTypes = [].concat(fileType);

package/dist/index.d.cts

@@ -179,6 +179,14 @@ declare class S3BucketUtil {
         directories: string[];
         files: ContentFile[];
     }>;
+    directoryListPaginated(directoryPath?: string, { pageSize, pageNumber, }?: {
+        pageSize?: number;
+        pageNumber?: number;
+    }): Promise<{
+        directories: string[];
+        files: ContentFile[];
+        totalFetched: number;
+    }>;
     /**
      * Get all files recursively (example for search/indexing)
      * @param directoryPath
@@ -221,6 +229,15 @@ declare class S3BucketUtil {
     directoryTree(directoryPath?: string): Promise<TreeDirectoryItem>;
     fileInfo(filePath: string): Promise<HeadObjectCommandOutput>;
     fileListInfo(directoryPath?: string, fileNamePrefix?: string): Promise<ContentFile[]>;
+    fileListInfoPaginated(directoryPath?: string, { fileNamePrefix, pageNumber, // 0-based: page 0 = items 0-99, page 1 = items 100-199, page 2 = items 200-299
+    pageSize, }?: {
+        fileNamePrefix?: string;
+        pageSize?: number;
+        pageNumber?: number;
+    }): Promise<{
+        files: ContentFile[];
+        totalFetched: number;
+    }>;
     taggingFile(filePath: string, tagVersion?: string): Promise<boolean>;
     fileVersion(filePath: string): Promise<string>;
     fileUrl(filePath: string, expiresIn?: number | StringValue): Promise<string>;
@@ -249,7 +266,7 @@ declare class S3BucketUtil {
     }): Promise<(req: Request$1 & any, res: Response & any, next: NextFunction & any) => Promise<any>>;
     private static fileFilter;
     private getFileSize;
-    getUploadFileMW(directory?: string, { acl, maxFileSize, filename: _filename, fileType, fileExt, metadata: customMetadata, }?: S3UploadOptions): Multer;
+    getUploadFileMW(directoryPath?: string, { acl, maxFileSize, filename: _filename, fileType, fileExt, metadata: customMetadata, }?: S3UploadOptions): Multer;
     /**
      * Middleware for uploading a single file
      * Adds the uploaded file info to req.s3File

package/dist/index.d.ts

@@ -179,6 +179,14 @@ declare class S3BucketUtil {
         directories: string[];
         files: ContentFile[];
     }>;
+    directoryListPaginated(directoryPath?: string, { pageSize, pageNumber, }?: {
+        pageSize?: number;
+        pageNumber?: number;
+    }): Promise<{
+        directories: string[];
+        files: ContentFile[];
+        totalFetched: number;
+    }>;
     /**
      * Get all files recursively (example for search/indexing)
      * @param directoryPath
@@ -221,6 +229,15 @@ declare class S3BucketUtil {
     directoryTree(directoryPath?: string): Promise<TreeDirectoryItem>;
     fileInfo(filePath: string): Promise<HeadObjectCommandOutput>;
     fileListInfo(directoryPath?: string, fileNamePrefix?: string): Promise<ContentFile[]>;
+    fileListInfoPaginated(directoryPath?: string, { fileNamePrefix, pageNumber, // 0-based: page 0 = items 0-99, page 1 = items 100-199, page 2 = items 200-299
+    pageSize, }?: {
+        fileNamePrefix?: string;
+        pageSize?: number;
+        pageNumber?: number;
+    }): Promise<{
+        files: ContentFile[];
+        totalFetched: number;
+    }>;
     taggingFile(filePath: string, tagVersion?: string): Promise<boolean>;
     fileVersion(filePath: string): Promise<string>;
     fileUrl(filePath: string, expiresIn?: number | StringValue): Promise<string>;
@@ -249,7 +266,7 @@ declare class S3BucketUtil {
     }): Promise<(req: Request$1 & any, res: Response & any, next: NextFunction & any) => Promise<any>>;
     private static fileFilter;
     private getFileSize;
-    getUploadFileMW(directory?: string, { acl, maxFileSize, filename: _filename, fileType, fileExt, metadata: customMetadata, }?: S3UploadOptions): Multer;
+    getUploadFileMW(directoryPath?: string, { acl, maxFileSize, filename: _filename, fileType, fileExt, metadata: customMetadata, }?: S3UploadOptions): Multer;
     /**
      * Middleware for uploading a single file
      * Adds the uploaded file info to req.s3File

package/dist/index.js

@@ -282,6 +282,7 @@ var parseRangeHeader = (range, contentLength, chunkSize) => {
   }
   return [start, Math.min(end, end)];
 };
+var getNormalizedPath = (directoryPath) => decodeURIComponent((directoryPath == null ? void 0 : directoryPath.replace(/^\/+/, "").replace(/\/+$/, "")) || "");
 var S3BucketUtil = class _S3BucketUtil {
   constructor({
     logger: logger2,
@@ -590,7 +591,7 @@ var S3BucketUtil = class _S3BucketUtil {
   // ##### DIRECTORY BLOCK ##########################
   createDirectory(directoryPath) {
     return __async(this, null, function* () {
-      let normalizedPath = decodeURIComponent((directoryPath == null ? void 0 : directoryPath.replace(/^\//, "").replace(/\/$/, "")) || "");
+      let normalizedPath = getNormalizedPath(directoryPath);
       if (!normalizedPath) throw new Error("No directory path provided");
       if (normalizedPath === "/") normalizedPath = "";
       const command = new PutObjectCommand({ Bucket: this.bucket, Key: `${normalizedPath}/` });
@@ -601,10 +602,8 @@ var S3BucketUtil = class _S3BucketUtil {
   deleteDirectory(directoryPath) {
     return __async(this, null, function* () {
       var _a2, _b, _c, _d, _e, _f, _g;
-      let normalizedPath = decodeURIComponent((directoryPath == null ? void 0 : directoryPath.replace(/^\//, "").replace(/\/$/, "")) || "");
-      if (!normalizedPath) {
-        throw new Error("No directory path provided");
-      }
+      let normalizedPath = getNormalizedPath(directoryPath);
+      if (!normalizedPath) throw new Error("No directory path provided");
       if (normalizedPath === "/") normalizedPath = "";
       let totalDeletedCount = 0;
       let ContinuationToken = void 0;
@@ -671,8 +670,8 @@ var S3BucketUtil = class _S3BucketUtil {
   }
   directoryList(directoryPath) {
     return __async(this, null, function* () {
-      let normalizedPath = decodeURIComponent((directoryPath == null ? void 0 : directoryPath.replace(/^\//, "").replace(/\/$/, "")) || "");
-      if (directoryPath !== "/" && directoryPath !== "" && directoryPath !== void 0) normalizedPath += "/";
+      let normalizedPath = getNormalizedPath(directoryPath);
+      if (normalizedPath !== "/" && directoryPath !== "" && directoryPath !== void 0) normalizedPath += "/";
       else normalizedPath = "";
       const result = yield this.execute(
         new ListObjectsV2Command({
@@ -696,14 +695,63 @@ var S3BucketUtil = class _S3BucketUtil {
       return { directories, files };
     });
   }
+  directoryListPaginated(_0) {
+    return __async(this, arguments, function* (directoryPath, {
+      pageSize = 100,
+      pageNumber = 0
+      // 0-based: page 0 = items 0-99, page 1 = items 100-199, page 2 = items 200-299
+    } = {}) {
+      let normalizedPath = getNormalizedPath(directoryPath);
+      if (normalizedPath !== "/" && directoryPath !== "" && directoryPath !== void 0) normalizedPath += "/";
+      else normalizedPath = "";
+      let continuationToken = void 0;
+      let currentPage = 0;
+      let allDirectories = [];
+      let allFiles = [];
+      while (currentPage <= pageNumber) {
+        const result = yield this.execute(
+          new ListObjectsV2Command({
+            Bucket: this.bucket,
+            Prefix: normalizedPath,
+            Delimiter: "/",
+            MaxKeys: pageSize,
+            ContinuationToken: continuationToken
+          })
+        );
+        if (currentPage === pageNumber) {
+          allDirectories = (result.CommonPrefixes || []).map((prefix) => prefix.Prefix).map((prefix) => {
+            const relativePath = prefix.replace(normalizedPath, "");
+            return relativePath.replace(/\/$/, "");
+          }).filter((dir) => dir);
+          allFiles = (result.Contents || []).filter((content) => {
+            var _a2;
+            return content.Key !== normalizedPath && !((_a2 = content.Key) == null ? void 0 : _a2.endsWith("/"));
+          }).map((content) => __spreadProps(__spreadValues({}, content), {
+            Name: content.Key.replace(normalizedPath, "") || content.Key,
+            LastModified: new Date(content.LastModified)
+          }));
+        }
+        continuationToken = result.NextContinuationToken;
+        if (!result.IsTruncated || !continuationToken) {
+          break;
+        }
+        currentPage++;
+      }
+      return {
+        directories: allDirectories,
+        files: allFiles,
+        totalFetched: allFiles.length + allDirectories.length
+      };
+    });
+  }
   /**
    * Get all files recursively (example for search/indexing)
    * @param directoryPath
    */
   directoryListRecursive(directoryPath) {
     return __async(this, null, function* () {
-      let normalizedPath = decodeURIComponent((directoryPath == null ? void 0 : directoryPath.replace(/^\//, "").replace(/\/$/, "")) || "");
-      if (directoryPath !== "/" && directoryPath !== "" && directoryPath !== void 0) normalizedPath += "/";
+      let normalizedPath = getNormalizedPath(directoryPath);
+      if (normalizedPath !== "/" && directoryPath !== "" && directoryPath !== void 0) normalizedPath += "/";
       else normalizedPath = "";
       const allDirectories = [];
       const allFiles = [];
@@ -767,7 +815,7 @@ var S3BucketUtil = class _S3BucketUtil {
    */
   directoryTree(directoryPath) {
     return __async(this, null, function* () {
-      let normalizedPath = decodeURIComponent((directoryPath == null ? void 0 : directoryPath.replace(/^\//, "").replace(/\/$/, "")) || "");
+      let normalizedPath = getNormalizedPath(directoryPath);
       const lastDirectory = directoryPath == null ? void 0 : directoryPath.split("/").pop();
       const { directories, files } = yield this.directoryList(normalizedPath);
       if (directoryPath !== "/" && directoryPath !== "" && directoryPath !== void 0) normalizedPath += "/";
@@ -798,7 +846,7 @@ var S3BucketUtil = class _S3BucketUtil {
   // ##### FILES BLOCK ##########################
   fileInfo(filePath) {
     return __async(this, null, function* () {
-      const normalizedKey = decodeURIComponent((filePath == null ? void 0 : filePath.replace(/^\//, "").replace(/\/$/, "")) || "");
+      const normalizedKey = getNormalizedPath(filePath);
       if (!normalizedKey || normalizedKey === "/") {
         throw new Error("No file key provided");
       }
@@ -809,8 +857,8 @@ var S3BucketUtil = class _S3BucketUtil {
   fileListInfo(directoryPath, fileNamePrefix) {
     return __async(this, null, function* () {
       var _a2, _b;
-      let normalizedPath = decodeURIComponent((directoryPath == null ? void 0 : directoryPath.replace(/^\//, "").replace(/\/$/, "")) || "");
-      if (directoryPath !== "/" && directoryPath !== "" && directoryPath !== void 0) normalizedPath += "/";
+      let normalizedPath = getNormalizedPath(directoryPath);
+      if (normalizedPath !== "/" && directoryPath !== "" && directoryPath !== void 0) normalizedPath += "/";
       else normalizedPath = "";
       const prefix = normalizedPath + (fileNamePrefix || "");
       const command = new ListObjectsCommand({
@@ -832,13 +880,65 @@ var S3BucketUtil = class _S3BucketUtil {
       return files;
     });
   }
+  fileListInfoPaginated(_0) {
+    return __async(this, arguments, function* (directoryPath, {
+      fileNamePrefix,
+      pageNumber = 0,
+      // 0-based: page 0 = items 0-99, page 1 = items 100-199, page 2 = items 200-299
+      pageSize = 100
+    } = {}) {
+      var _a2, _b;
+      let normalizedPath = getNormalizedPath(directoryPath);
+      if (normalizedPath !== "/" && directoryPath !== "" && directoryPath !== void 0) normalizedPath += "/";
+      else normalizedPath = "";
+      const prefix = normalizedPath + (fileNamePrefix || "");
+      let continuationToken;
+      let currentPage = 0;
+      let resultFiles = [];
+      while (currentPage <= pageNumber) {
+        const result = yield this.execute(
+          new ListObjectsV2Command({
+            Bucket: this.bucket,
+            Prefix: prefix,
+            Delimiter: "/",
+            MaxKeys: pageSize,
+            ContinuationToken: continuationToken
+          })
+        );
+        if (currentPage === pageNumber) {
+          resultFiles = ((_a2 = result.Contents) != null ? _a2 : []).filter((v) => v).map(
+            (content) => {
+              var _a3, _b2;
+              return __spreadProps(__spreadValues({}, content), {
+                Name: (_b2 = (_a3 = content.Key) == null ? void 0 : _a3.replace(prefix, "")) != null ? _b2 : content.Key,
+                LastModified: content.LastModified ? new Date(content.LastModified) : null
+              });
+            }
+          ).filter((content) => content.Name);
+        }
+        continuationToken = result.NextContinuationToken;
+        if (!result.IsTruncated || !continuationToken) {
+          break;
+        }
+        currentPage++;
+      }
+      (_b = this.logger) == null ? void 0 : _b.debug(null, "file list info paginated", {
+        prefix,
+        pageNumber,
+        pageSize,
+        fileCount: resultFiles.length
+      });
+      return {
+        files: resultFiles,
+        totalFetched: resultFiles.length
+      };
+    });
+  }
   taggingFile(filePath, tagVersion = "1.0.0") {
     return __async(this, null, function* () {
       try {
-        const normalizedKey = decodeURIComponent((filePath == null ? void 0 : filePath.replace(/^\//, "").replace(/\/$/, "")) || "");
-        if (!normalizedKey || normalizedKey === "/") {
-          throw new Error("No file key provided");
-        }
+        const normalizedKey = getNormalizedPath(filePath);
+        if (!normalizedKey || normalizedKey === "/") throw new Error("No file key provided");
         const command = new PutObjectTaggingCommand({
           Bucket: this.bucket,
           Key: normalizedKey,
@@ -854,10 +954,8 @@ var S3BucketUtil = class _S3BucketUtil {
   fileVersion(filePath) {
     return __async(this, null, function* () {
       var _a2, _b;
-      const normalizedKey = decodeURIComponent((filePath == null ? void 0 : filePath.replace(/^\//, "").replace(/\/$/, "")) || "");
-      if (!normalizedKey || normalizedKey === "/") {
-        throw new Error("No file key provided");
-      }
+      const normalizedKey = getNormalizedPath(filePath);
+      if (!normalizedKey || normalizedKey === "/") throw new Error("No file key provided");
       const command = new GetObjectTaggingCommand({ Bucket: this.bucket, Key: normalizedKey });
       const result = yield this.execute(command);
       const tag = (_a2 = result.TagSet) == null ? void 0 : _a2.find((tag2) => tag2.Key === "version");
@@ -867,10 +965,8 @@ var S3BucketUtil = class _S3BucketUtil {
   fileUrl(filePath, expiresIn = "15m") {
     return __async(this, null, function* () {
       var _a2;
-      const normalizedKey = decodeURIComponent((filePath == null ? void 0 : filePath.replace(/^\//, "").replace(/\/$/, "")) || "");
-      if (!normalizedKey || normalizedKey === "/") {
-        throw new Error("No file key provided");
-      }
+      const normalizedKey = getNormalizedPath(filePath);
+      if (!normalizedKey || normalizedKey === "/") throw new Error("No file key provided");
       const expiresInSeconds = typeof expiresIn === "number" ? expiresIn : ms(expiresIn) / 1e3;
       const command = new GetObjectCommand({ Bucket: this.bucket, Key: normalizedKey });
       const url = yield getSignedUrl(this.s3Client, command, {
@@ -884,10 +980,8 @@ var S3BucketUtil = class _S3BucketUtil {
   sizeOf(filePath, unit = "bytes") {
     return __async(this, null, function* () {
       var _a2, _b, _c;
-      const normalizedKey = decodeURIComponent((filePath == null ? void 0 : filePath.replace(/^\//, "").replace(/\/$/, "")) || "");
-      if (!normalizedKey || normalizedKey === "/") {
-        throw new Error("No file key provided");
-      }
+      const normalizedKey = getNormalizedPath(filePath);
+      if (!normalizedKey || normalizedKey === "/") throw new Error("No file key provided");
       try {
         const command = new HeadObjectCommand({ Bucket: this.bucket, Key: normalizedKey });
         const headObject = yield this.execute(command);
@@ -915,10 +1009,8 @@ var S3BucketUtil = class _S3BucketUtil {
     return __async(this, null, function* () {
       var _a2;
       try {
-        const normalizedKey = decodeURIComponent((filePath == null ? void 0 : filePath.replace(/^\//, "").replace(/\/$/, "")) || "");
-        if (!normalizedKey || normalizedKey === "/") {
-          throw new Error("No file key provided");
-        }
+        const normalizedKey = getNormalizedPath(filePath);
+        if (!normalizedKey || normalizedKey === "/") throw new Error("No file key provided");
         const command = new HeadObjectCommand({ Bucket: this.bucket, Key: normalizedKey });
         yield this.execute(command);
         return true;
@@ -932,10 +1024,8 @@ var S3BucketUtil = class _S3BucketUtil {
   }
   fileContent(filePath, format = "buffer") {
     return __async(this, null, function* () {
-      const normalizedKey = decodeURIComponent((filePath == null ? void 0 : filePath.replace(/^\//, "").replace(/\/$/, "")) || "");
-      if (!normalizedKey || normalizedKey === "/") {
-        throw new Error("No file key provided");
-      }
+      const normalizedKey = getNormalizedPath(filePath);
+      if (!normalizedKey || normalizedKey === "/") throw new Error("No file key provided");
       const command = new GetObjectCommand({ Bucket: this.bucket, Key: normalizedKey });
       const result = yield this.execute(command);
       if (!result.Body) {
@@ -967,10 +1057,8 @@ var S3BucketUtil = class _S3BucketUtil {
   }
   uploadFile(_0, _1) {
     return __async(this, arguments, function* (filePath, fileData, acl = "private" /* private */, version = "1.0.0") {
-      const normalizedKey = decodeURIComponent((filePath == null ? void 0 : filePath.replace(/^\//, "").replace(/\/$/, "")) || "");
-      if (!normalizedKey || normalizedKey === "/") {
-        throw new Error("No file key provided");
-      }
+      const normalizedKey = getNormalizedPath(filePath);
+      if (!normalizedKey || normalizedKey === "/") throw new Error("No file key provided");
       const upload = new Upload({
         client: this.s3Client,
         params: {
@@ -992,10 +1080,8 @@ var S3BucketUtil = class _S3BucketUtil {
   }
   deleteFile(filePath) {
     return __async(this, null, function* () {
-      const normalizedKey = decodeURIComponent((filePath == null ? void 0 : filePath.replace(/^\//, "").replace(/\/$/, "")) || "");
-      if (!normalizedKey || normalizedKey === "/") {
-        throw new Error("No file key provided");
-      }
+      const normalizedKey = getNormalizedPath(filePath);
+      if (!normalizedKey || normalizedKey === "/") throw new Error("No file key provided");
       const command = new DeleteObjectCommand({ Bucket: this.bucket, Key: normalizedKey });
       return yield this.execute(command);
     });
@@ -1007,10 +1093,8 @@ var S3BucketUtil = class _S3BucketUtil {
       checkFileExists = true,
       abortSignal
     } = {}) {
-      const normalizedKey = decodeURIComponent((filePath == null ? void 0 : filePath.replace(/^\//, "").replace(/\/$/, "")) || "");
-      if (!normalizedKey || normalizedKey === "/") {
-        throw new Error("No file key provided");
-      }
+      const normalizedKey = getNormalizedPath(filePath);
+      if (!normalizedKey || normalizedKey === "/") throw new Error("No file key provided");
       if (checkFileExists) {
         const isExists = yield this.fileExists(normalizedKey);
         if (!isExists) return null;
@@ -1033,10 +1117,8 @@ var S3BucketUtil = class _S3BucketUtil {
       abortSignal
     }) {
       var _a2;
-      const normalizedKey = decodeURIComponent((filePath == null ? void 0 : filePath.replace(/^\//, "").replace(/\/$/, "")) || "");
-      if (!normalizedKey || normalizedKey === "/") {
-        throw new Error("No file key provided");
-      }
+      const normalizedKey = getNormalizedPath(filePath);
+      if (!normalizedKey || normalizedKey === "/") throw new Error("No file key provided");
       try {
         const cmd = new GetObjectCommand(__spreadValues({
           Bucket: this.bucket,
@@ -1075,9 +1157,7 @@ var S3BucketUtil = class _S3BucketUtil {
     }) {
       return (req, res, next) => __async(this, null, function* () {
         var _a2, _b, _c, _d, _e;
-        const filePaths = [].concat(filePath).map((filePath2) => {
-          return decodeURIComponent((filePath2 == null ? void 0 : filePath2.replace(/^\//, "").replace(/\/$/, "")) || "");
-        }).filter((v) => v && v !== "/");
+        const filePaths = [].concat(filePath).map((filePath2) => getNormalizedPath(filePath2)).filter((v) => v && v !== "/");
         if (!filePaths.length) {
           throw new Error("No file keys provided");
         }
@@ -1218,10 +1298,8 @@ var S3BucketUtil = class _S3BucketUtil {
           (_a3 = stream == null ? void 0 : stream.destroy) == null ? void 0 : _a3.call(stream);
         };
         req.once("close", onClose);
-        const normalizedKey = decodeURIComponent((filePath == null ? void 0 : filePath.replace(/^\//, "").replace(/\/$/, "")) || "");
-        if (!normalizedKey || normalizedKey === "/") {
-          throw new Error("No file key provided");
-        }
+        const normalizedKey = getNormalizedPath(filePath);
+        if (!normalizedKey || normalizedKey === "/") throw new Error("No file key provided");
         try {
           const isExists = yield this.fileExists(normalizedKey);
           if (!isExists) {
@@ -1292,10 +1370,8 @@ var S3BucketUtil = class _S3BucketUtil {
     }) {
       return (req, res, next) => __async(this, null, function* () {
         var _a2, _b, _c, _d, _e, _f;
-        const normalizedKey = decodeURIComponent((fileKey == null ? void 0 : fileKey.replace(/^\//, "").replace(/\/$/, "")) || "");
-        if (!normalizedKey || normalizedKey === "/") {
-          throw new Error("No file key provided");
-        }
+        const normalizedKey = getNormalizedPath(fileKey);
+        if (!normalizedKey || normalizedKey === "/") throw new Error("No file key provided");
         const isExists = yield this.fileExists(normalizedKey);
         const fileSize = yield this.sizeOf(normalizedKey);
         let Range;
@@ -1423,7 +1499,7 @@ var S3BucketUtil = class _S3BucketUtil {
     }
     return fileSize;
   }
-  getUploadFileMW(directory, {
+  getUploadFileMW(directoryPath, {
     acl = "private" /* private */,
     maxFileSize,
     filename: _filename,
@@ -1431,8 +1507,8 @@ var S3BucketUtil = class _S3BucketUtil {
     fileExt = [],
     metadata: customMetadata
   } = {}) {
-    let normalizedPath = decodeURIComponent((directory == null ? void 0 : directory.replace(/^\//, "").replace(/\/$/, "")) || "");
-    if (directory !== "/" && directory !== "" && directory !== void 0) normalizedPath += "/";
+    let normalizedPath = getNormalizedPath(directoryPath);
+    if (normalizedPath !== "/" && directoryPath !== "" && directoryPath !== void 0) normalizedPath += "/";
     else normalizedPath = "";
     const fileSize = this.getFileSize(maxFileSize);
     const fileTypes = [].concat(fileType);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hdriel/aws-utils",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "description": "Simplified AWS SDK (v3) utilities for S3 (upload, download, streaming) with TypeScript support",
   "author": "Hadriel Benjo (https://github.com/hdriel)",
   "type": "module",
@@ -31,7 +31,7 @@
     "build:watch": "tsc --watch",
     "format": "prettier --write .",
     "clean": "rimraf ./dist",
-    "yalc:publish": "pnpm run build && yalc publish --private --push && cd demo && npm run yalc:attach",
+    "yalc:publish": "pnpm run build && yalc publish --private --push && cd demo && pnpm add @hdriel/aws-utils && cd ../demo && npm run yalc:attach",
     "docker:localstack:restart": "cross-env NODE_ENV=localhost && docker-compose -f docker-compose.localstack.yml --env-file .env.local up -d --build",
     "docker:localstack:down": "docker-compose -f docker-compose.localstack.yml down"
   },