express-storage 2.0.2 → 3.0.0

package/dist/esm/utils/index.js

@@ -0,0 +1,11 @@
+/**
+ * express-storage/utils
+ *
+ * Standalone utility functions for file handling, retries, and concurrency.
+ *
+ * @example
+ * import { withRetry, formatFileSize, withConcurrencyLimit } from 'express-storage/utils';
+ */
+export { generateUniqueFileName, sanitizeFileName, validateFileName, hasPathTraversal, encodePathSegments, isValidMimeType, validateFolderPath, validateFileForUpload, createMonthBasedPath, ensureDirectoryExists, formatFileSize, validateFileSize, validateFileType, getFileExtension, isImageFile, isDocumentFile, detectMimeType, withRetry, sleep, withConcurrencyLimit, } from './file.utils.js';
+export { InMemoryRateLimiter, isRateLimiterAdapter } from './rate-limiter.js';
+//# sourceMappingURL=index.js.map

package/dist/esm/utils/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/utils/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EACL,sBAAsB,EACtB,gBAAgB,EAChB,gBAAgB,EAChB,gBAAgB,EAChB,kBAAkB,EAClB,eAAe,EACf,kBAAkB,EAClB,qBAAqB,EACrB,oBAAoB,EACpB,qBAAqB,EACrB,cAAc,EACd,gBAAgB,EAChB,gBAAgB,EAChB,gBAAgB,EAChB,WAAW,EACX,cAAc,EACd,cAAc,EACd,SAAS,EACT,KAAK,EACL,oBAAoB,GACrB,MAAM,iBAAiB,CAAC;AAIzB,OAAO,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/esm/utils/rate-limiter.d.ts

@@ -0,0 +1,40 @@
+import { RateLimiterAdapter, RateLimitOptions } from '../types/storage.types.js';
+/**
+ * O(1) sliding window counter rate limiter for presigned URL generation.
+ *
+ * Uses a two-bucket sliding window algorithm: tracks request counts for the
+ * current and previous windows, then estimates the effective count with a
+ * time-weighted blend. This provides smooth rate limiting without storing
+ * individual timestamps.
+ *
+ * All operations are O(1) time and O(1) space regardless of request volume.
+ *
+ * Suitable for single-process applications. For clustered/multi-process
+ * deployments, implement `RateLimiterAdapter` backed by a shared store.
+ */
+export declare class InMemoryRateLimiter implements RateLimiterAdapter {
+    private maxRequests;
+    private windowMs;
+    private currentCount;
+    private previousCount;
+    private windowStart;
+    constructor(options: RateLimitOptions);
+    /**
+     * Rotates the window buckets if the current window has elapsed.
+     */
+    private slide;
+    /**
+     * Returns the estimated request count across the sliding window,
+     * blending the previous window's count proportionally with elapsed time.
+     */
+    private getEstimatedCount;
+    tryAcquire(): boolean;
+    getRemainingRequests(): number;
+    getResetTime(): number;
+}
+/**
+ * Returns true if the value is a RateLimiterAdapter (has the required methods),
+ * as opposed to plain RateLimitOptions.
+ */
+export declare function isRateLimiterAdapter(value: unknown): value is RateLimiterAdapter;
+//# sourceMappingURL=rate-limiter.d.ts.map

package/dist/esm/utils/rate-limiter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limiter.d.ts","sourceRoot":"","sources":["../../../src/utils/rate-limiter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAEjF;;;;;;;;;;;;GAYG;AACH,qBAAa,mBAAoB,YAAW,kBAAkB;IAC5D,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,YAAY,CAAa;IACjC,OAAO,CAAC,aAAa,CAAa;IAClC,OAAO,CAAC,WAAW,CAAS;gBAEhB,OAAO,EAAE,gBAAgB;IAMrC;;OAEG;IACH,OAAO,CAAC,KAAK;IAeb;;;OAGG;IACH,OAAO,CAAC,iBAAiB;IAMzB,UAAU,IAAI,OAAO;IAWrB,oBAAoB,IAAI,MAAM;IAK9B,YAAY,IAAI,MAAM;CAQvB;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,kBAAkB,CAOhF"}

package/dist/esm/utils/rate-limiter.js

@@ -0,0 +1,82 @@
+/**
+ * O(1) sliding window counter rate limiter for presigned URL generation.
+ *
+ * Uses a two-bucket sliding window algorithm: tracks request counts for the
+ * current and previous windows, then estimates the effective count with a
+ * time-weighted blend. This provides smooth rate limiting without storing
+ * individual timestamps.
+ *
+ * All operations are O(1) time and O(1) space regardless of request volume.
+ *
+ * Suitable for single-process applications. For clustered/multi-process
+ * deployments, implement `RateLimiterAdapter` backed by a shared store.
+ */
+export class InMemoryRateLimiter {
+    maxRequests;
+    windowMs;
+    currentCount = 0;
+    previousCount = 0;
+    windowStart;
+    constructor(options) {
+        this.maxRequests = options.maxRequests;
+        this.windowMs = options.windowMs || 60000;
+        this.windowStart = Date.now();
+    }
+    /**
+     * Rotates the window buckets if the current window has elapsed.
+     */
+    slide() {
+        const now = Date.now();
+        const elapsed = now - this.windowStart;
+        if (elapsed >= this.windowMs * 2) {
+            this.previousCount = 0;
+            this.currentCount = 0;
+            this.windowStart = now;
+        }
+        else if (elapsed >= this.windowMs) {
+            this.previousCount = this.currentCount;
+            this.currentCount = 0;
+            this.windowStart += this.windowMs;
+        }
+    }
+    /**
+     * Returns the estimated request count across the sliding window,
+     * blending the previous window's count proportionally with elapsed time.
+     */
+    getEstimatedCount() {
+        const elapsed = Date.now() - this.windowStart;
+        const weight = Math.max(0, (this.windowMs - elapsed) / this.windowMs);
+        return this.previousCount * weight + this.currentCount;
+    }
+    tryAcquire() {
+        this.slide();
+        if (this.getEstimatedCount() >= this.maxRequests) {
+            return false;
+        }
+        this.currentCount++;
+        return true;
+    }
+    getRemainingRequests() {
+        this.slide();
+        return Math.max(0, Math.floor(this.maxRequests - this.getEstimatedCount()));
+    }
+    getResetTime() {
+        this.slide();
+        if (this.currentCount === 0 && this.previousCount === 0) {
+            return 0;
+        }
+        const elapsed = Date.now() - this.windowStart;
+        return Math.max(0, this.windowMs - elapsed);
+    }
+}
+/**
+ * Returns true if the value is a RateLimiterAdapter (has the required methods),
+ * as opposed to plain RateLimitOptions.
+ */
+export function isRateLimiterAdapter(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        'tryAcquire' in value &&
+        typeof value.tryAcquire === 'function');
+}
+//# sourceMappingURL=rate-limiter.js.map

package/dist/esm/utils/rate-limiter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limiter.js","sourceRoot":"","sources":["../../../src/utils/rate-limiter.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;GAYG;AACH,MAAM,OAAO,mBAAmB;IACtB,WAAW,CAAS;IACpB,QAAQ,CAAS;IACjB,YAAY,GAAW,CAAC,CAAC;IACzB,aAAa,GAAW,CAAC,CAAC;IAC1B,WAAW,CAAS;IAE5B,YAAY,OAAyB;QACnC,IAAI,CAAC,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC;QACvC,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,KAAK,CAAC;QAC1C,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IAChC,CAAC;IAED;;OAEG;IACK,KAAK;QACX,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACvB,MAAM,OAAO,GAAG,GAAG,GAAG,IAAI,CAAC,WAAW,CAAC;QAEvC,IAAI,OAAO,IAAI,IAAI,CAAC,QAAQ,GAAG,CAAC,EAAE,CAAC;YACjC,IAAI,CAAC,aAAa,GAAG,CAAC,CAAC;YACvB,IAAI,CAAC,YAAY,GAAG,CAAC,CAAC;YACtB,IAAI,CAAC,WAAW,GAAG,GAAG,CAAC;QACzB,CAAC;aAAM,IAAI,OAAO,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YACpC,IAAI,CAAC,aAAa,GAAG,IAAI,CAAC,YAAY,CAAC;YACvC,IAAI,CAAC,YAAY,GAAG,CAAC,CAAC;YACtB,IAAI,CAAC,WAAW,IAAI,IAAI,CAAC,QAAQ,CAAC;QACpC,CAAC;IACH,CAAC;IAED;;;OAGG;IACK,iBAAiB;QACvB,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,WAAW,CAAC;QAC9C,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC,CAAC;QACtE,OAAO,IAAI,CAAC,aAAa,GAAG,MAAM,GAAG,IAAI,CAAC,YAAY,CAAC;IACzD,CAAC;IAED,UAAU;QACR,IAAI,CAAC,KAAK,EAAE,CAAC;QAEb,IAAI,IAAI,CAAC,iBAAiB,EAAE,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC;YACjD,OAAO,KAAK,CAAC;QACf,CAAC;QAED,IAAI,CAAC,YAAY,EAAE,CAAC;QACpB,OAAO,IAAI,CAAC;IACd,CAAC;IAED,oBAAoB;QAClB,IAAI,CAAC,KAAK,EAAE,CAAC;QACb,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC,iBAAiB,EAAE,CAAC,CAAC,CAAC;IAC9E,CAAC;IAED,YAAY;QACV,IAAI,CAAC,KAAK,EAAE,CAAC;QACb,IAAI,IAAI,CAAC,YAAY,KAAK,CAAC,IAAI,IAAI,CAAC,aAAa,KAAK,CAAC,EAAE,CAAC;YACxD,OAAO,CAAC,CAAC;QACX,CAAC;QACD,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,WAAW,CAAC;QAC9C,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC,CAAC;IAC9C,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,UAAU,oBAAoB,CAAC,KAAc;IACjD,OAAO,CACL,OAAO,KAAK,KAAK,QAAQ;QACzB,KAAK,KAAK,IAAI;QACd,YAAY,IAAI,KAAK;QACrB,OAAQ,KAA4B,CAAC,UAAU,KAAK,UAAU,CAC/D,CAAC;AACJ,CAAC"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "express-storage",
-  "version": "2.0.2",
-  "description": "One API for all cloud storage: AWS S3, Google Cloud, Azure & local disk. Secure Express.js file uploads with presigned URLs, validation, and zero-config provider switching. Built-in path traversal prevention, file validation, and automatic filename sanitization.",
+  "version": "3.0.0",
+  "description": "Express.js file upload middleware for AWS S3, Google Cloud Storage, Azure Blob & local disk. Unified API with presigned URLs, file validation, streaming uploads, TypeScript support, and zero-config provider switching.",
   "homepage": "https://github.com/th3hero/express-storage#readme",
   "bugs": {
     "url": "https://github.com/th3hero/express-storage/issues"
@@ -12,79 +12,95 @@
   },
   "license": "MIT",
   "author": "Alok Kumar (th3hero)",
-  "type": "module",
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/cjs/index.d.ts",
   "exports": {
     ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js",
-      "require": "./dist/index.js",
-      "default": "./dist/index.js"
+      "import": {
+        "types": "./dist/esm/index.d.ts",
+        "default": "./dist/esm/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/index.d.ts",
+        "default": "./dist/cjs/index.js"
+      }
+    },
+    "./drivers": {
+      "import": {
+        "types": "./dist/esm/drivers/index.d.ts",
+        "default": "./dist/esm/drivers/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/drivers/index.d.ts",
+        "default": "./dist/cjs/drivers/index.js"
+      }
+    },
+    "./utils": {
+      "import": {
+        "types": "./dist/esm/utils/index.d.ts",
+        "default": "./dist/esm/utils/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/utils/index.d.ts",
+        "default": "./dist/cjs/utils/index.js"
+      }
+    },
+    "./config": {
+      "import": {
+        "types": "./dist/esm/config/index.d.ts",
+        "default": "./dist/esm/config/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/config/index.d.ts",
+        "default": "./dist/cjs/config/index.js"
+      }
     }
   },
+  "sideEffects": false,
   "files": [
     "dist",
+    "src",
     "README.md",
     "LICENSE"
   ],
   "keywords": [
     "express",
     "file-upload",
-    "storage",
     "upload",
-    "file-storage",
+    "storage",
     "cloud-storage",
     "s3",
     "aws-s3",
-    "amazon-s3",
     "gcs",
     "google-cloud-storage",
     "azure",
-    "azure-blob",
     "azure-blob-storage",
-    "blob-storage",
+    "multer",
+    "multer-alternative",
     "presigned-url",
-    "presigned-upload",
-    "direct-upload",
-    "secure-upload",
     "file-validation",
-    "multer",
-    "multer-storage",
     "typescript",
     "nodejs",
-    "expressjs",
-    "file-manager",
-    "upload-manager",
-    "storage-driver",
-    "multi-cloud",
-    "hybrid-cloud",
-    "file-security",
-    "upload-security",
     "multipart-upload",
+    "streaming-upload",
     "file-upload-middleware",
     "express-middleware",
-    "multer-alternative",
-    "unified-storage",
-    "storage-abstraction",
-    "file-streaming",
-    "resumable-upload",
-    "cloud-agnostic",
-    "provider-agnostic",
-    "s3-upload",
-    "gcs-upload",
-    "azure-upload",
-    "bucket-storage",
-    "multer-s3-alternative",
-    "cloud-file-storage"
+    "object-storage",
+    "multi-cloud",
+    "secure-upload",
+    "s3-upload"
   ],
   "scripts": {
-    "build": "tsc",
-    "dev": "tsc --watch",
+    "build": "npm run build:esm && npm run build:cjs && npm run build:fixup",
+    "build:esm": "tsc -p tsconfig.esm.json",
+    "build:cjs": "tsc -p tsconfig.cjs.json",
+    "build:fixup": "echo '{\"type\":\"commonjs\"}' > dist/cjs/package.json && echo '{\"type\":\"module\"}' > dist/esm/package.json",
+    "dev": "tsc -p tsconfig.esm.json --watch",
     "clean": "rm -rf dist",
     "prepublishOnly": "npm run clean && npm run build",
-    "lint": "eslint src --ext .ts",
-    "lint:fix": "eslint src --ext .ts --fix",
+    "lint": "eslint src",
+    "lint:fix": "eslint src --fix",
     "format": "prettier --write src/**/*.ts",
     "type-check": "tsc --noEmit",
     "test": "vitest run",
@@ -92,34 +108,57 @@
     "test:coverage": "vitest run --coverage"
   },
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=20.0.0"
   },
   "dependencies": {
+    "dotenv": "^16.3.0"
+  },
+  "peerDependencies": {
     "@aws-sdk/client-s3": "^3.600.0",
     "@aws-sdk/lib-storage": "^3.600.0",
     "@aws-sdk/s3-request-presigner": "^3.600.0",
     "@azure/identity": "^4.0.0",
     "@azure/storage-blob": "^12.17.0",
     "@google-cloud/storage": "^7.7.0",
-    "dotenv": "^16.3.0",
-    "tslib": "^2.6.0"
-  },
-  "peerDependencies": {
     "express": "^4.18.0 || ^5.0.0",
     "multer": "^1.4.5-lts.1 || ^2.0.0"
   },
   "peerDependenciesMeta": {
     "express": {
-      "optional": false
+      "optional": true
     },
     "multer": {
       "optional": true
+    },
+    "@aws-sdk/client-s3": {
+      "optional": true
+    },
+    "@aws-sdk/lib-storage": {
+      "optional": true
+    },
+    "@aws-sdk/s3-request-presigner": {
+      "optional": true
+    },
+    "@azure/identity": {
+      "optional": true
+    },
+    "@azure/storage-blob": {
+      "optional": true
+    },
+    "@google-cloud/storage": {
+      "optional": true
     }
   },
   "overrides": {
-    "fast-xml-parser": "^5.3.4"
+    "minimatch": ">=10.2.1"
   },
   "devDependencies": {
+    "@aws-sdk/client-s3": "^3.600.0",
+    "@aws-sdk/lib-storage": "^3.600.0",
+    "@aws-sdk/s3-request-presigner": "^3.600.0",
+    "@azure/identity": "^4.0.0",
+    "@azure/storage-blob": "^12.17.0",
+    "@google-cloud/storage": "^7.7.0",
     "@types/express": "^5.0.6",
     "@types/multer": "^2.0.0",
     "@types/node": "^25.2.0",
@@ -127,7 +166,6 @@
     "@typescript-eslint/parser": "^8.54.0",
     "@vitest/coverage-v8": "^4.0.18",
     "eslint": "^9.39.2",
-    "memfs": "^4.56.10",
     "prettier": "^3.8.1",
     "typescript": "^5.9.3",
     "vitest": "^4.0.18"

package/src/config/index.ts

@@ -0,0 +1,17 @@
+/**
+ * express-storage/config
+ * 
+ * Configuration loading, validation, and environment variable utilities.
+ * 
+ * @example
+ * import { loadAndValidateConfig, validateStorageConfig } from 'express-storage/config';
+ */
+
+export {
+  loadAndValidateConfig,
+  validateStorageConfig,
+  initializeDotenv,
+  resetDotenvInitialization,
+  loadEnvironmentConfig,
+  environmentToStorageConfig,
+} from '../utils/config.utils.js';