@geekmidas/storage 0.0.4 → 0.0.5

package/README.md

@@ -11,6 +11,7 @@ A comprehensive, type-safe storage client for cloud storage services with suppor
 - **Direct uploads**: Upload files directly to storage without intermediate servers
 - **Flexible configuration**: Support for custom endpoints (useful for MinIO, LocalStack, etc.)
 - **Modern async/await API**: Promise-based interface throughout
+- **URL caching**: Built-in support for caching presigned URLs to reduce API calls and improve performance
 
 ## Installation
 
@@ -32,6 +33,7 @@ npm install @aws-sdk/client-s3 @aws-sdk/s3-presigned-post @aws-sdk/s3-request-pr
 
 ```typescript
 import { AmazonStorageClient } from '@geekmidas/storage/aws';
+import { InMemoryCache } from '@geekmidas/cache/memory';
 
 // Create client with credentials
 const storage = AmazonStorageClient.create({
@@ -41,6 +43,16 @@ const storage = AmazonStorageClient.create({
   secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
 });
 
+// Create client with caching enabled
+const cache = new InMemoryCache<string>();
+const storageWithCache = AmazonStorageClient.create({
+  bucket: 'my-bucket',
+  region: 'us-east-1',
+  accessKeyId: process.env.AWS_ACCESS_KEY_ID,
+  secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
+  cache,
+});
+
 // Upload a file directly
 await storage.upload('documents/readme.txt', 'Hello, World!', 'text/plain');
 
@@ -82,6 +94,7 @@ The core interface that all storage providers implement:
 ```typescript
 interface StorageClient {
   readonly provider: StorageProvider;
+  readonly cache?: Cache<string>;
   
   // Direct upload
   upload(key: string, data: string | Buffer, contentType: string): Promise<void>;
@@ -114,6 +127,8 @@ AmazonStorageClient.create(options: AmazonStorageClientCreateOptions)
 - `secretAccessKey`: AWS secret access key
 - `endpoint`: Custom S3 endpoint (useful for MinIO, LocalStack)
 - `acl`: Canned ACL for uploads (default: `authenticated-read`)
+- `cache`: Optional cache implementation for storing presigned URLs
+- `forcePathStyle`: Force path-style URLs (useful for MinIO)
 
 #### Methods
 
@@ -132,7 +147,7 @@ await storage.upload('files/binary.dat', buffer, 'application/octet-stream');
 
 ##### `getDownloadURL(file: File, expiresIn?: number): Promise<string>`
 
-Generate a presigned download URL.
+Generate a presigned download URL. When a cache is configured, URLs will be cached based on the file path.
 
 ```typescript
 // Simple download URL
@@ -148,6 +163,12 @@ const url = await storage.getDownloadURL({
 const url = await storage.getDownloadURL({ path: 'documents/file.pdf' }, 3600);
 ```
 
+**Caching behavior:**
+- URLs are cached with key format: `download-url:{file.path}`
+- Cache TTL is set to `expiresIn - 60` seconds (with 1 minute buffer)
+- URLs with expiration < 60 seconds are not cached
+- Cached URLs are returned immediately without generating new presigned URLs
+
 ##### `getUploadURL(params: GetUploadParams, expiresIn?: number): Promise<string>`
 
 Generate a presigned PUT upload URL.
@@ -257,6 +278,7 @@ enum StorageProvider {
 ```typescript
 import { S3Client } from '@aws-sdk/client-s3';
 import { AmazonStorageClient, AmazonCannedAccessControlList } from '@geekmidas/storage/aws';
+import { InMemoryCache } from '@geekmidas/cache/memory';
 
 const s3Client = new S3Client({
   region: 'us-east-1',
@@ -266,11 +288,21 @@ const s3Client = new S3Client({
   },
 });
 
+// Without cache
 const storage = new AmazonStorageClient(
   s3Client,
   'my-bucket',
   AmazonCannedAccessControlList.PublicRead
 );
+
+// With cache
+const cache = new InMemoryCache<string>();
+const storageWithCache = new AmazonStorageClient(
+  s3Client,
+  'my-bucket',
+  AmazonCannedAccessControlList.PublicRead,
+  cache
+);
 ```
 
 ### Access Control Lists (ACLs)
@@ -294,6 +326,44 @@ Available ACLs:
 - `LogDeliveryWrite` - Log delivery service gets write access
 - `AwsExecRead` - Amazon EC2 gets read access for AMI bundles
 
+### Caching
+
+Caching presigned URLs can significantly reduce the number of API calls to AWS S3 and improve performance.
+
+```typescript
+import { AmazonStorageClient } from '@geekmidas/storage/aws';
+import { InMemoryCache } from '@geekmidas/cache/memory';
+import { UpstashCache } from '@geekmidas/cache/upstash';
+
+// In-memory cache for development/testing
+const memoryCache = new InMemoryCache<string>();
+const storage = AmazonStorageClient.create({
+  bucket: 'my-bucket',
+  cache: memoryCache,
+});
+
+// Redis cache for production
+const redisCache = new UpstashCache<string>({
+  url: process.env.UPSTASH_REDIS_URL,
+  token: process.env.UPSTASH_REDIS_TOKEN,
+});
+const productionStorage = AmazonStorageClient.create({
+  bucket: 'my-bucket',
+  cache: redisCache,
+});
+
+// Cache behavior example
+const url1 = await storage.getDownloadURL({ path: 'file.pdf' }); // Generates new URL
+const url2 = await storage.getDownloadURL({ path: 'file.pdf' }); // Returns cached URL
+console.log(url1 === url2); // true
+```
+
+**Cache keys and TTL:**
+- Download URLs are cached with key: `download-url:{path}`
+- Cache TTL is automatically calculated as `expiresIn - 60` seconds
+- URLs expiring in less than 60 seconds are not cached
+- Upload URLs are not cached (they are typically single-use)
+
 ### Error Handling
 
 ```typescript

package/dist/{AmazonStorageClient-DJMWn8vO.mjs → AmazonStorageClient-Bkw-x2o2.mjs}

@@ -7,7 +7,7 @@ import { getSignedUrl } from "@aws-sdk/s3-request-presigner";
 var AmazonStorageClient = class AmazonStorageClient {
 	provider = StorageProvider.AWSS3;
 	static create(options) {
-		const { bucket, region, accessKeyId, acl, endpoint, secretAccessKey, forcePathStyle = false } = options;
+		const { bucket, region, accessKeyId, acl, endpoint, secretAccessKey, forcePathStyle = false, cache } = options;
 		const hasCredentials = accessKeyId && secretAccessKey;
 		const credentials = hasCredentials ? {
 			accessKeyId,
@@ -19,12 +19,13 @@ var AmazonStorageClient = class AmazonStorageClient {
 			endpoint,
 			forcePathStyle
 		});
-		return new AmazonStorageClient(client, bucket, acl);
+		return new AmazonStorageClient(client, bucket, acl, cache);
 	}
-	constructor(client, bucket, acl = AmazonCannedAccessControlList.AuthenticatedRead) {
+	constructor(client, bucket, acl = AmazonCannedAccessControlList.AuthenticatedRead, cache) {
 		this.client = client;
 		this.bucket = bucket;
 		this.acl = acl;
+		this.cache = cache;
 	}
 	getVersionDownloadURL(file, versionId) {
 		const ResponseContentDisposition = file.name ? `attachment; filename=${encodeURIComponent(file.name)}` : void 0;
@@ -47,14 +48,20 @@ var AmazonStorageClient = class AmazonStorageClient {
 			createdAt: version.LastModified || /* @__PURE__ */ new Date()
 		}));
 	}
-	getDownloadURL(file, expiresIn = 60 * 60) {
+	async getDownloadURL(file, expiresIn = 60 * 60) {
+		const cacheKey = `download-url:${file.path}`;
+		const cachedURL = await this.cache?.get(cacheKey);
+		if (cachedURL) return cachedURL;
 		const ResponseContentDisposition = file.name ? `attachment; filename=${encodeURIComponent(file.name)}` : void 0;
 		const command = new GetObjectCommand({
 			Bucket: this.bucket,
 			Key: file.path,
 			ResponseContentDisposition
 		});
-		return getSignedUrl(this.client, command, { expiresIn });
+		const url = await getSignedUrl(this.client, command, { expiresIn });
+		const cacheExpiration = Math.max(expiresIn - 60, 0);
+		if (cacheExpiration) await this.cache?.set(cacheKey, url, cacheExpiration);
+		return url;
 	}
 	async getUploadURL(params, expiresIn = 60 * 60) {
 		const command = new PutObjectCommand({

package/dist/{AmazonStorageClient-C16fG3G4.d.cts → AmazonStorageClient-DaktozmE.d.mts}

@@ -1,14 +1,16 @@
-import { DocumentVersion, File, GetUploadParams, GetUploadResponse, StorageClient, StorageProvider } from "./StorageClient-D-y4QLDq.cjs";
+import { DocumentVersion, File, GetUploadParams, GetUploadResponse, StorageClient, StorageProvider } from "./StorageClient-CveQoxJa.mjs";
 import { S3Client } from "@aws-sdk/client-s3";
+import { Cache } from "@geekmidas/cache";
 
 //#region src/AmazonStorageClient.d.ts
 declare class AmazonStorageClient implements StorageClient {
   private readonly client;
   private readonly bucket;
   private readonly acl;
+  readonly cache?: Cache<string>;
   readonly provider = StorageProvider.AWSS3;
   static create(options: AmazonStorageClientCreateOptions): AmazonStorageClient;
-  constructor(client: S3Client, bucket: string, acl?: AmazonCannedAccessControlList);
+  constructor(client: S3Client, bucket: string, acl?: AmazonCannedAccessControlList, cache?: Cache<string>);
   getVersionDownloadURL(file: File, versionId: string): Promise<string>;
   getVersions(key: string): Promise<DocumentVersion[]>;
   getDownloadURL(file: File, expiresIn?: number): Promise<string>;
@@ -34,6 +36,7 @@ interface AmazonStorageClientCreateOptions {
   secretAccessKey?: string;
   endpoint?: string;
   forcePathStyle?: boolean;
+  cache?: Cache<string>;
 }
 //#endregion
 export { AmazonCannedAccessControlList, AmazonStorageClient };

package/dist/{AmazonStorageClient-CP8Tx5oE.d.mts → AmazonStorageClient-aduVU3_p.d.cts}

@@ -1,14 +1,16 @@
-import { DocumentVersion, File, GetUploadParams, GetUploadResponse, StorageClient, StorageProvider } from "./StorageClient-CJbHRTVV.mjs";
+import { DocumentVersion, File, GetUploadParams, GetUploadResponse, StorageClient, StorageProvider } from "./StorageClient-CcOAW3YV.cjs";
 import { S3Client } from "@aws-sdk/client-s3";
+import { Cache } from "@geekmidas/cache";
 
 //#region src/AmazonStorageClient.d.ts
 declare class AmazonStorageClient implements StorageClient {
   private readonly client;
   private readonly bucket;
   private readonly acl;
+  readonly cache?: Cache<string>;
   readonly provider = StorageProvider.AWSS3;
   static create(options: AmazonStorageClientCreateOptions): AmazonStorageClient;
-  constructor(client: S3Client, bucket: string, acl?: AmazonCannedAccessControlList);
+  constructor(client: S3Client, bucket: string, acl?: AmazonCannedAccessControlList, cache?: Cache<string>);
   getVersionDownloadURL(file: File, versionId: string): Promise<string>;
   getVersions(key: string): Promise<DocumentVersion[]>;
   getDownloadURL(file: File, expiresIn?: number): Promise<string>;
@@ -34,6 +36,7 @@ interface AmazonStorageClientCreateOptions {
   secretAccessKey?: string;
   endpoint?: string;
   forcePathStyle?: boolean;
+  cache?: Cache<string>;
 }
 //#endregion
 export { AmazonCannedAccessControlList, AmazonStorageClient };

package/dist/{AmazonStorageClient-DT9DeKVz.cjs → AmazonStorageClient-tyGekctm.cjs}

@@ -8,7 +8,7 @@ const __aws_sdk_s3_request_presigner = require_chunk.__toESM(require("@aws-sdk/s
 var AmazonStorageClient = class AmazonStorageClient {
 	provider = require_StorageClient.StorageProvider.AWSS3;
 	static create(options) {
-		const { bucket, region, accessKeyId, acl, endpoint, secretAccessKey, forcePathStyle = false } = options;
+		const { bucket, region, accessKeyId, acl, endpoint, secretAccessKey, forcePathStyle = false, cache } = options;
 		const hasCredentials = accessKeyId && secretAccessKey;
 		const credentials = hasCredentials ? {
 			accessKeyId,
@@ -20,12 +20,13 @@ var AmazonStorageClient = class AmazonStorageClient {
 			endpoint,
 			forcePathStyle
 		});
-		return new AmazonStorageClient(client, bucket, acl);
+		return new AmazonStorageClient(client, bucket, acl, cache);
 	}
-	constructor(client, bucket, acl = AmazonCannedAccessControlList.AuthenticatedRead) {
+	constructor(client, bucket, acl = AmazonCannedAccessControlList.AuthenticatedRead, cache) {
 		this.client = client;
 		this.bucket = bucket;
 		this.acl = acl;
+		this.cache = cache;
 	}
 	getVersionDownloadURL(file, versionId) {
 		const ResponseContentDisposition = file.name ? `attachment; filename=${encodeURIComponent(file.name)}` : void 0;
@@ -48,14 +49,20 @@ var AmazonStorageClient = class AmazonStorageClient {
 			createdAt: version.LastModified || /* @__PURE__ */ new Date()
 		}));
 	}
-	getDownloadURL(file, expiresIn = 60 * 60) {
+	async getDownloadURL(file, expiresIn = 60 * 60) {
+		const cacheKey = `download-url:${file.path}`;
+		const cachedURL = await this.cache?.get(cacheKey);
+		if (cachedURL) return cachedURL;
 		const ResponseContentDisposition = file.name ? `attachment; filename=${encodeURIComponent(file.name)}` : void 0;
 		const command = new __aws_sdk_client_s3.GetObjectCommand({
 			Bucket: this.bucket,
 			Key: file.path,
 			ResponseContentDisposition
 		});
-		return (0, __aws_sdk_s3_request_presigner.getSignedUrl)(this.client, command, { expiresIn });
+		const url = await (0, __aws_sdk_s3_request_presigner.getSignedUrl)(this.client, command, { expiresIn });
+		const cacheExpiration = Math.max(expiresIn - 60, 0);
+		if (cacheExpiration) await this.cache?.set(cacheKey, url, cacheExpiration);
+		return url;
 	}
 	async getUploadURL(params, expiresIn = 60 * 60) {
 		const command = new __aws_sdk_client_s3.PutObjectCommand({

package/dist/AmazonStorageClient.cjs

@@ -1,5 +1,5 @@
 require('./StorageClient-BDRVrMJj.cjs');
-const require_AmazonStorageClient = require('./AmazonStorageClient-DT9DeKVz.cjs');
+const require_AmazonStorageClient = require('./AmazonStorageClient-tyGekctm.cjs');
 
 exports.AmazonCannedAccessControlList = require_AmazonStorageClient.AmazonCannedAccessControlList;
 exports.AmazonStorageClient = require_AmazonStorageClient.AmazonStorageClient;

package/dist/AmazonStorageClient.d.cts

@@ -1,3 +1,3 @@
-import "./StorageClient-D-y4QLDq.cjs";
-import { AmazonCannedAccessControlList, AmazonStorageClient } from "./AmazonStorageClient-C16fG3G4.cjs";
+import "./StorageClient-CcOAW3YV.cjs";
+import { AmazonCannedAccessControlList, AmazonStorageClient } from "./AmazonStorageClient-aduVU3_p.cjs";
 export { AmazonCannedAccessControlList, AmazonStorageClient };

package/dist/AmazonStorageClient.d.mts

@@ -1,3 +1,3 @@
-import "./StorageClient-CJbHRTVV.mjs";
-import { AmazonCannedAccessControlList, AmazonStorageClient } from "./AmazonStorageClient-CP8Tx5oE.mjs";
+import "./StorageClient-CveQoxJa.mjs";
+import { AmazonCannedAccessControlList, AmazonStorageClient } from "./AmazonStorageClient-DaktozmE.mjs";
 export { AmazonCannedAccessControlList, AmazonStorageClient };

package/dist/AmazonStorageClient.mjs

@@ -1,4 +1,4 @@
 import "./StorageClient-CZGIC_fz.mjs";
-import { AmazonCannedAccessControlList, AmazonStorageClient } from "./AmazonStorageClient-DJMWn8vO.mjs";
+import { AmazonCannedAccessControlList, AmazonStorageClient } from "./AmazonStorageClient-Bkw-x2o2.mjs";
 
 export { AmazonCannedAccessControlList, AmazonStorageClient };

package/dist/{StorageClient-D-y4QLDq.d.cts → StorageClient-CcOAW3YV.d.cts}

@@ -1,3 +1,5 @@
+import { Cache } from "@geekmidas/cache";
+
 //#region src/StorageClient.d.ts
 interface DocumentVersion {
   id: string;
@@ -10,6 +12,7 @@ declare enum StorageProvider {
 }
 interface StorageClient {
   readonly provider: StorageProvider;
+  readonly cache?: Cache<string>;
   /**
    * Get a URL to upload a file to.
    *

package/dist/{StorageClient-CJbHRTVV.d.mts → StorageClient-CveQoxJa.d.mts}

@@ -1,3 +1,5 @@
+import { Cache } from "@geekmidas/cache";
+
 //#region src/StorageClient.d.ts
 interface DocumentVersion {
   id: string;
@@ -10,6 +12,7 @@ declare enum StorageProvider {
 }
 interface StorageClient {
   readonly provider: StorageProvider;
+  readonly cache?: Cache<string>;
   /**
    * Get a URL to upload a file to.
    *

package/dist/StorageClient.d.cts

@@ -1,2 +1,2 @@
-import { DocumentVersion, File, GetUploadParams, GetUploadResponse, StorageClient, StorageProvider, UploadField } from "./StorageClient-D-y4QLDq.cjs";
+import { DocumentVersion, File, GetUploadParams, GetUploadResponse, StorageClient, StorageProvider, UploadField } from "./StorageClient-CcOAW3YV.cjs";
 export { DocumentVersion, File, GetUploadParams, GetUploadResponse, StorageClient, StorageProvider, UploadField };

package/dist/StorageClient.d.mts

@@ -1,2 +1,2 @@
-import { DocumentVersion, File, GetUploadParams, GetUploadResponse, StorageClient, StorageProvider, UploadField } from "./StorageClient-CJbHRTVV.mjs";
+import { DocumentVersion, File, GetUploadParams, GetUploadResponse, StorageClient, StorageProvider, UploadField } from "./StorageClient-CveQoxJa.mjs";
 export { DocumentVersion, File, GetUploadParams, GetUploadResponse, StorageClient, StorageProvider, UploadField };

package/dist/__tests__/AmazonStorageClient.spec.cjs

@@ -1,8 +1,9 @@
 const require_chunk = require('../chunk-DWy1uDak.cjs');
 const require_StorageClient = require('../StorageClient-BDRVrMJj.cjs');
-const require_AmazonStorageClient = require('../AmazonStorageClient-DT9DeKVz.cjs');
+const require_AmazonStorageClient = require('../AmazonStorageClient-tyGekctm.cjs');
 const require_vi_bdSIJ99Y = require('../vi.bdSIJ99Y-D0m6qImj.cjs');
 const __aws_sdk_client_s3 = require_chunk.__toESM(require("@aws-sdk/client-s3"));
+const __geekmidas_cache_memory = require_chunk.__toESM(require("@geekmidas/cache/memory"));
 
 //#region src/__tests__/AmazonStorageClient.spec.ts
 require_vi_bdSIJ99Y.describe("AmazonStorageClient Integration Tests", () => {
@@ -229,6 +230,119 @@ require_vi_bdSIJ99Y.describe("AmazonStorageClient Integration Tests", () => {
 			require_vi_bdSIJ99Y.globalExpect(storageClient.provider).toBe(require_StorageClient.StorageProvider.AWSS3);
 		});
 	});
+	require_vi_bdSIJ99Y.describe("cache functionality", () => {
+		require_vi_bdSIJ99Y.it("should cache download URLs", async () => {
+			const cache = new __geekmidas_cache_memory.InMemoryCache();
+			const clientWithCache = require_AmazonStorageClient.AmazonStorageClient.create({
+				bucket: testBucket,
+				region: "us-east-1",
+				accessKeyId: "geekmidas",
+				secretAccessKey: "geekmidas",
+				endpoint: "http://localhost:9000",
+				forcePathStyle: true,
+				cache
+			});
+			const key = "test-files/cache-test.txt";
+			await clientWithCache.upload(key, testContent, testContentType);
+			const url1 = await clientWithCache.getDownloadURL({ path: key });
+			const url2 = await clientWithCache.getDownloadURL({ path: key });
+			require_vi_bdSIJ99Y.globalExpect(url1).toBe(url2);
+			const cacheKey = `download-url:${key}`;
+			const cachedUrl = await cache.get(cacheKey);
+			require_vi_bdSIJ99Y.globalExpect(cachedUrl).toBe(url1);
+		});
+		require_vi_bdSIJ99Y.it("should respect cache expiration based on URL expiry", async () => {
+			const cache = new __geekmidas_cache_memory.InMemoryCache();
+			const clientWithCache = require_AmazonStorageClient.AmazonStorageClient.create({
+				bucket: testBucket,
+				region: "us-east-1",
+				accessKeyId: "geekmidas",
+				secretAccessKey: "geekmidas",
+				endpoint: "http://localhost:9000",
+				forcePathStyle: true,
+				cache
+			});
+			const key = "test-files/cache-expiry.txt";
+			await clientWithCache.upload(key, testContent, testContentType);
+			await clientWithCache.getDownloadURL({ path: key }, 30);
+			const cacheKey = `download-url:${key}`;
+			const cachedShortUrl = await cache.get(cacheKey);
+			require_vi_bdSIJ99Y.globalExpect(cachedShortUrl).toBeUndefined();
+			const longExpiryUrl = await clientWithCache.getDownloadURL({ path: key }, 3600);
+			const cachedLongUrl = await cache.get(cacheKey);
+			require_vi_bdSIJ99Y.globalExpect(cachedLongUrl).toBe(longExpiryUrl);
+		});
+		require_vi_bdSIJ99Y.it("should use cached URL when available", async () => {
+			const cache = new __geekmidas_cache_memory.InMemoryCache();
+			const clientWithCache = require_AmazonStorageClient.AmazonStorageClient.create({
+				bucket: testBucket,
+				region: "us-east-1",
+				accessKeyId: "geekmidas",
+				secretAccessKey: "geekmidas",
+				endpoint: "http://localhost:9000",
+				forcePathStyle: true,
+				cache
+			});
+			const key = "test-files/pre-cached.txt";
+			const cachedUrl = "https://pre-cached-url.example.com";
+			const cacheKey = `download-url:${key}`;
+			await cache.set(cacheKey, cachedUrl);
+			const url = await clientWithCache.getDownloadURL({ path: key });
+			require_vi_bdSIJ99Y.globalExpect(url).toBe(cachedUrl);
+		});
+		require_vi_bdSIJ99Y.it("should work without cache", async () => {
+			const clientNoCache = require_AmazonStorageClient.AmazonStorageClient.create({
+				bucket: testBucket,
+				region: "us-east-1",
+				accessKeyId: "geekmidas",
+				secretAccessKey: "geekmidas",
+				endpoint: "http://localhost:9000",
+				forcePathStyle: true
+			});
+			const key = "test-files/no-cache.txt";
+			await clientNoCache.upload(key, testContent, testContentType);
+			const url1 = await clientNoCache.getDownloadURL({ path: key });
+			const url2 = await clientNoCache.getDownloadURL({ path: key });
+			require_vi_bdSIJ99Y.globalExpect(url1).toMatch(/^http:\/\/localhost:9000\/geekmidas\/test-files\/no-cache\.txt/);
+			require_vi_bdSIJ99Y.globalExpect(url2).toMatch(/^http:\/\/localhost:9000\/geekmidas\/test-files\/no-cache\.txt/);
+		});
+		require_vi_bdSIJ99Y.it("should pass cache to constructor", () => {
+			const cache = new __geekmidas_cache_memory.InMemoryCache();
+			const s3Client = new __aws_sdk_client_s3.S3Client({
+				region: "us-east-1",
+				credentials: {
+					accessKeyId: "geekmidas",
+					secretAccessKey: "geekmidas"
+				},
+				endpoint: "http://localhost:9000",
+				forcePathStyle: true
+			});
+			const clientWithCache = new require_AmazonStorageClient.AmazonStorageClient(s3Client, testBucket, require_AmazonStorageClient.AmazonCannedAccessControlList.PublicRead, cache);
+			require_vi_bdSIJ99Y.globalExpect(clientWithCache.cache).toBe(cache);
+		});
+	});
+	require_vi_bdSIJ99Y.describe("getVersionDownloadURL", () => {
+		require_vi_bdSIJ99Y.it("should generate version-specific download URL", async () => {
+			const versionKey = "test-files/version-download.txt";
+			const versionId = "test-version-id";
+			await client.upload(versionKey, testContent, testContentType);
+			const downloadUrl = await client.getVersionDownloadURL({
+				path: versionKey,
+				name: "versioned-file.txt"
+			}, versionId);
+			require_vi_bdSIJ99Y.globalExpect(downloadUrl).toMatch(/^http:\/\/localhost:9000\/geekmidas\/test-files\/version-download\.txt/);
+			require_vi_bdSIJ99Y.globalExpect(downloadUrl).toContain("X-Amz-Algorithm=AWS4-HMAC-SHA256");
+			require_vi_bdSIJ99Y.globalExpect(downloadUrl).toContain("response-content-disposition=attachment%3B%20filename%3Dversioned-file.txt");
+		});
+		require_vi_bdSIJ99Y.it("should generate version URL without filename", async () => {
+			const versionKey = "test-files/version-no-name.txt";
+			const versionId = "test-version-id";
+			await client.upload(versionKey, testContent, testContentType);
+			const downloadUrl = await client.getVersionDownloadURL({ path: versionKey }, versionId);
+			require_vi_bdSIJ99Y.globalExpect(downloadUrl).toMatch(/^http:\/\/localhost:9000\/geekmidas\/test-files\/version-no-name\.txt/);
+			require_vi_bdSIJ99Y.globalExpect(downloadUrl).not.toContain("response-content-disposition");
+		});
+	});
 });
 
 //#endregion

package/dist/__tests__/AmazonStorageClient.spec.mjs

@@ -1,7 +1,8 @@
 import { beforeAll, describe, globalExpect, it } from "../vi.bdSIJ99Y-CucmVasy.mjs";
 import { StorageProvider } from "../StorageClient-CZGIC_fz.mjs";
-import { AmazonCannedAccessControlList, AmazonStorageClient } from "../AmazonStorageClient-DJMWn8vO.mjs";
+import { AmazonCannedAccessControlList, AmazonStorageClient } from "../AmazonStorageClient-Bkw-x2o2.mjs";
 import { S3Client } from "@aws-sdk/client-s3";
+import { InMemoryCache } from "@geekmidas/cache/memory";
 
 //#region src/__tests__/AmazonStorageClient.spec.ts
 describe("AmazonStorageClient Integration Tests", () => {
@@ -228,6 +229,119 @@ describe("AmazonStorageClient Integration Tests", () => {
 			globalExpect(storageClient.provider).toBe(StorageProvider.AWSS3);
 		});
 	});
+	describe("cache functionality", () => {
+		it("should cache download URLs", async () => {
+			const cache = new InMemoryCache();
+			const clientWithCache = AmazonStorageClient.create({
+				bucket: testBucket,
+				region: "us-east-1",
+				accessKeyId: "geekmidas",
+				secretAccessKey: "geekmidas",
+				endpoint: "http://localhost:9000",
+				forcePathStyle: true,
+				cache
+			});
+			const key = "test-files/cache-test.txt";
+			await clientWithCache.upload(key, testContent, testContentType);
+			const url1 = await clientWithCache.getDownloadURL({ path: key });
+			const url2 = await clientWithCache.getDownloadURL({ path: key });
+			globalExpect(url1).toBe(url2);
+			const cacheKey = `download-url:${key}`;
+			const cachedUrl = await cache.get(cacheKey);
+			globalExpect(cachedUrl).toBe(url1);
+		});
+		it("should respect cache expiration based on URL expiry", async () => {
+			const cache = new InMemoryCache();
+			const clientWithCache = AmazonStorageClient.create({
+				bucket: testBucket,
+				region: "us-east-1",
+				accessKeyId: "geekmidas",
+				secretAccessKey: "geekmidas",
+				endpoint: "http://localhost:9000",
+				forcePathStyle: true,
+				cache
+			});
+			const key = "test-files/cache-expiry.txt";
+			await clientWithCache.upload(key, testContent, testContentType);
+			await clientWithCache.getDownloadURL({ path: key }, 30);
+			const cacheKey = `download-url:${key}`;
+			const cachedShortUrl = await cache.get(cacheKey);
+			globalExpect(cachedShortUrl).toBeUndefined();
+			const longExpiryUrl = await clientWithCache.getDownloadURL({ path: key }, 3600);
+			const cachedLongUrl = await cache.get(cacheKey);
+			globalExpect(cachedLongUrl).toBe(longExpiryUrl);
+		});
+		it("should use cached URL when available", async () => {
+			const cache = new InMemoryCache();
+			const clientWithCache = AmazonStorageClient.create({
+				bucket: testBucket,
+				region: "us-east-1",
+				accessKeyId: "geekmidas",
+				secretAccessKey: "geekmidas",
+				endpoint: "http://localhost:9000",
+				forcePathStyle: true,
+				cache
+			});
+			const key = "test-files/pre-cached.txt";
+			const cachedUrl = "https://pre-cached-url.example.com";
+			const cacheKey = `download-url:${key}`;
+			await cache.set(cacheKey, cachedUrl);
+			const url = await clientWithCache.getDownloadURL({ path: key });
+			globalExpect(url).toBe(cachedUrl);
+		});
+		it("should work without cache", async () => {
+			const clientNoCache = AmazonStorageClient.create({
+				bucket: testBucket,
+				region: "us-east-1",
+				accessKeyId: "geekmidas",
+				secretAccessKey: "geekmidas",
+				endpoint: "http://localhost:9000",
+				forcePathStyle: true
+			});
+			const key = "test-files/no-cache.txt";
+			await clientNoCache.upload(key, testContent, testContentType);
+			const url1 = await clientNoCache.getDownloadURL({ path: key });
+			const url2 = await clientNoCache.getDownloadURL({ path: key });
+			globalExpect(url1).toMatch(/^http:\/\/localhost:9000\/geekmidas\/test-files\/no-cache\.txt/);
+			globalExpect(url2).toMatch(/^http:\/\/localhost:9000\/geekmidas\/test-files\/no-cache\.txt/);
+		});
+		it("should pass cache to constructor", () => {
+			const cache = new InMemoryCache();
+			const s3Client = new S3Client({
+				region: "us-east-1",
+				credentials: {
+					accessKeyId: "geekmidas",
+					secretAccessKey: "geekmidas"
+				},
+				endpoint: "http://localhost:9000",
+				forcePathStyle: true
+			});
+			const clientWithCache = new AmazonStorageClient(s3Client, testBucket, AmazonCannedAccessControlList.PublicRead, cache);
+			globalExpect(clientWithCache.cache).toBe(cache);
+		});
+	});
+	describe("getVersionDownloadURL", () => {
+		it("should generate version-specific download URL", async () => {
+			const versionKey = "test-files/version-download.txt";
+			const versionId = "test-version-id";
+			await client.upload(versionKey, testContent, testContentType);
+			const downloadUrl = await client.getVersionDownloadURL({
+				path: versionKey,
+				name: "versioned-file.txt"
+			}, versionId);
+			globalExpect(downloadUrl).toMatch(/^http:\/\/localhost:9000\/geekmidas\/test-files\/version-download\.txt/);
+			globalExpect(downloadUrl).toContain("X-Amz-Algorithm=AWS4-HMAC-SHA256");
+			globalExpect(downloadUrl).toContain("response-content-disposition=attachment%3B%20filename%3Dversioned-file.txt");
+		});
+		it("should generate version URL without filename", async () => {
+			const versionKey = "test-files/version-no-name.txt";
+			const versionId = "test-version-id";
+			await client.upload(versionKey, testContent, testContentType);
+			const downloadUrl = await client.getVersionDownloadURL({ path: versionKey }, versionId);
+			globalExpect(downloadUrl).toMatch(/^http:\/\/localhost:9000\/geekmidas\/test-files\/version-no-name\.txt/);
+			globalExpect(downloadUrl).not.toContain("response-content-disposition");
+		});
+	});
 });
 
 //#endregion

package/dist/aws.cjs

@@ -1,5 +1,5 @@
 require('./StorageClient-BDRVrMJj.cjs');
-const require_AmazonStorageClient = require('./AmazonStorageClient-DT9DeKVz.cjs');
+const require_AmazonStorageClient = require('./AmazonStorageClient-tyGekctm.cjs');
 
 exports.AmazonCannedAccessControlList = require_AmazonStorageClient.AmazonCannedAccessControlList;
 exports.AmazonStorageClient = require_AmazonStorageClient.AmazonStorageClient;

package/dist/aws.d.cts

@@ -1,3 +1,3 @@
-import { DocumentVersion, File, GetUploadParams, GetUploadResponse, StorageClient } from "./StorageClient-D-y4QLDq.cjs";
-import { AmazonCannedAccessControlList, AmazonStorageClient } from "./AmazonStorageClient-C16fG3G4.cjs";
+import { DocumentVersion, File, GetUploadParams, GetUploadResponse, StorageClient } from "./StorageClient-CcOAW3YV.cjs";
+import { AmazonCannedAccessControlList, AmazonStorageClient } from "./AmazonStorageClient-aduVU3_p.cjs";
 export { AmazonCannedAccessControlList, AmazonStorageClient, DocumentVersion, File, GetUploadParams, GetUploadResponse, StorageClient };

package/dist/aws.d.mts

@@ -1,3 +1,3 @@
-import { DocumentVersion, File, GetUploadParams, GetUploadResponse, StorageClient } from "./StorageClient-CJbHRTVV.mjs";
-import { AmazonCannedAccessControlList, AmazonStorageClient } from "./AmazonStorageClient-CP8Tx5oE.mjs";
+import { DocumentVersion, File, GetUploadParams, GetUploadResponse, StorageClient } from "./StorageClient-CveQoxJa.mjs";
+import { AmazonCannedAccessControlList, AmazonStorageClient } from "./AmazonStorageClient-DaktozmE.mjs";
 export { AmazonCannedAccessControlList, AmazonStorageClient, DocumentVersion, File, GetUploadParams, GetUploadResponse, StorageClient };

package/dist/aws.mjs

@@ -1,4 +1,4 @@
 import "./StorageClient-CZGIC_fz.mjs";
-import { AmazonCannedAccessControlList, AmazonStorageClient } from "./AmazonStorageClient-DJMWn8vO.mjs";
+import { AmazonCannedAccessControlList, AmazonStorageClient } from "./AmazonStorageClient-Bkw-x2o2.mjs";
 
 export { AmazonCannedAccessControlList, AmazonStorageClient };

package/dist/index.d.cts

@@ -1,2 +1,2 @@
-import { StorageClient } from "./StorageClient-D-y4QLDq.cjs";
+import { StorageClient } from "./StorageClient-CcOAW3YV.cjs";
 export { StorageClient };

package/dist/index.d.mts

@@ -1,2 +1,2 @@
-import { StorageClient } from "./StorageClient-CJbHRTVV.mjs";
+import { StorageClient } from "./StorageClient-CveQoxJa.mjs";
 export { StorageClient };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geekmidas/storage",
-  "version": "0.0.4",
+  "version": "0.0.5",
   "private": false,
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
@@ -19,7 +19,9 @@
       "require": "./dist/index.cjs"
     }
   },
-  "dependencies": {},
+  "dependencies": {
+    "@geekmidas/cache": "0.0.7"
+  },
   "peerDependencies": {
     "zod": "~3.25.67",
     "@aws-sdk/client-s3": "~3.844.0",

package/src/AmazonStorageClient.ts

@@ -7,6 +7,7 @@ import {
 import { createPresignedPost } from '@aws-sdk/s3-presigned-post';
 import { getSignedUrl } from '@aws-sdk/s3-request-presigner';
 
+import type { Cache } from '@geekmidas/cache';
 import {
   type DocumentVersion,
   type File,
@@ -18,6 +19,7 @@ import {
 
 export class AmazonStorageClient implements StorageClient {
   readonly provider = StorageProvider.AWSS3;
+
   static create(
     options: AmazonStorageClientCreateOptions,
   ): AmazonStorageClient {
@@ -29,6 +31,7 @@ export class AmazonStorageClient implements StorageClient {
       endpoint,
       secretAccessKey,
       forcePathStyle = false,
+      cache,
     } = options;
     const hasCredentials = accessKeyId && secretAccessKey;
     const credentials = hasCredentials
@@ -42,12 +45,13 @@ export class AmazonStorageClient implements StorageClient {
       forcePathStyle,
     });
 
-    return new AmazonStorageClient(client, bucket, acl);
+    return new AmazonStorageClient(client, bucket, acl, cache);
   }
   constructor(
     private readonly client: S3Client,
     private readonly bucket: string,
     private readonly acl = AmazonCannedAccessControlList.AuthenticatedRead,
+    readonly cache?: Cache<string>,
   ) {}
 
   getVersionDownloadURL(file: File, versionId: string): Promise<string> {
@@ -79,7 +83,14 @@ export class AmazonStorageClient implements StorageClient {
     }));
   }
 
-  getDownloadURL(file: File, expiresIn = 60 * 60): Promise<string> {
+  async getDownloadURL(file: File, expiresIn = 60 * 60): Promise<string> {
+    const cacheKey = `download-url:${file.path}`;
+    const cachedURL = await this.cache?.get(cacheKey);
+
+    if (cachedURL) {
+      return cachedURL;
+    }
+
     const ResponseContentDisposition = file.name
       ? `attachment; filename=${encodeURIComponent(file.name)}`
       : undefined;
@@ -90,7 +101,14 @@ export class AmazonStorageClient implements StorageClient {
       ResponseContentDisposition,
     });
 
-    return getSignedUrl(this.client, command, { expiresIn });
+    const url = await getSignedUrl(this.client, command, { expiresIn });
+    const cacheExpiration = Math.max(expiresIn - 60, 0);
+
+    if (cacheExpiration) {
+      await this.cache?.set(cacheKey, url, cacheExpiration);
+    }
+
+    return url;
   }
 
   async getUploadURL(
@@ -173,4 +191,5 @@ interface AmazonStorageClientCreateOptions {
   secretAccessKey?: string;
   endpoint?: string;
   forcePathStyle?: boolean;
+  cache?: Cache<string>;
 }

package/src/StorageClient.ts

@@ -1,3 +1,4 @@
+import type { Cache } from '@geekmidas/cache';
 export interface DocumentVersion {
   id: string;
   createdAt: Date;
@@ -11,6 +12,7 @@ export enum StorageProvider {
 
 export interface StorageClient {
   readonly provider: StorageProvider;
+  readonly cache?: Cache<string>;
   /**
    * Get a URL to upload a file to.
    *

package/src/__tests__/AmazonStorageClient.spec.ts

@@ -1,4 +1,5 @@
 import { S3Client } from '@aws-sdk/client-s3';
+import { InMemoryCache } from '@geekmidas/cache/memory';
 import { beforeAll, describe, expect, it } from 'vitest';
 import {
   AmazonCannedAccessControlList,
@@ -324,4 +325,186 @@ describe('AmazonStorageClient Integration Tests', () => {
       expect(storageClient.provider).toBe(StorageProvider.AWSS3);
     });
   });
+
+  describe('cache functionality', () => {
+    it('should cache download URLs', async () => {
+      const cache = new InMemoryCache<string>();
+      const clientWithCache = AmazonStorageClient.create({
+        bucket: testBucket,
+        region: 'us-east-1',
+        accessKeyId: 'geekmidas',
+        secretAccessKey: 'geekmidas',
+        endpoint: 'http://localhost:9000',
+        forcePathStyle: true,
+        cache,
+      });
+
+      const key = 'test-files/cache-test.txt';
+      await clientWithCache.upload(key, testContent, testContentType);
+
+      // First call should generate and cache the URL
+      const url1 = await clientWithCache.getDownloadURL({ path: key });
+
+      // Second call should return the cached URL
+      const url2 = await clientWithCache.getDownloadURL({ path: key });
+
+      // URLs should be identical (same cached value)
+      expect(url1).toBe(url2);
+
+      // Verify the URL was cached
+      const cacheKey = `download-url:${key}`;
+      const cachedUrl = await cache.get(cacheKey);
+      expect(cachedUrl).toBe(url1);
+    });
+
+    it('should respect cache expiration based on URL expiry', async () => {
+      const cache = new InMemoryCache<string>();
+      const clientWithCache = AmazonStorageClient.create({
+        bucket: testBucket,
+        region: 'us-east-1',
+        accessKeyId: 'geekmidas',
+        secretAccessKey: 'geekmidas',
+        endpoint: 'http://localhost:9000',
+        forcePathStyle: true,
+        cache,
+      });
+
+      const key = 'test-files/cache-expiry.txt';
+      await clientWithCache.upload(key, testContent, testContentType);
+
+      // Generate URL with short expiry that won't be cached
+      await clientWithCache.getDownloadURL({ path: key }, 30); // 30 seconds
+
+      // Check cache doesn't contain the URL (too short to cache)
+      const cacheKey = `download-url:${key}`;
+      const cachedShortUrl = await cache.get(cacheKey);
+      expect(cachedShortUrl).toBeUndefined();
+
+      // Generate URL with longer expiry that will be cached
+      const longExpiryUrl = await clientWithCache.getDownloadURL(
+        { path: key },
+        3600,
+      ); // 1 hour
+
+      // Check cache contains the URL
+      const cachedLongUrl = await cache.get(cacheKey);
+      expect(cachedLongUrl).toBe(longExpiryUrl);
+    });
+
+    it('should use cached URL when available', async () => {
+      const cache = new InMemoryCache<string>();
+      const clientWithCache = AmazonStorageClient.create({
+        bucket: testBucket,
+        region: 'us-east-1',
+        accessKeyId: 'geekmidas',
+        secretAccessKey: 'geekmidas',
+        endpoint: 'http://localhost:9000',
+        forcePathStyle: true,
+        cache,
+      });
+
+      const key = 'test-files/pre-cached.txt';
+      const cachedUrl = 'https://pre-cached-url.example.com';
+      const cacheKey = `download-url:${key}`;
+
+      // Pre-populate cache
+      await cache.set(cacheKey, cachedUrl);
+
+      // Get download URL should return cached value
+      const url = await clientWithCache.getDownloadURL({ path: key });
+      expect(url).toBe(cachedUrl);
+    });
+
+    it('should work without cache', async () => {
+      // Client without cache should work normally
+      const clientNoCache = AmazonStorageClient.create({
+        bucket: testBucket,
+        region: 'us-east-1',
+        accessKeyId: 'geekmidas',
+        secretAccessKey: 'geekmidas',
+        endpoint: 'http://localhost:9000',
+        forcePathStyle: true,
+      });
+
+      const key = 'test-files/no-cache.txt';
+      await clientNoCache.upload(key, testContent, testContentType);
+
+      const url1 = await clientNoCache.getDownloadURL({ path: key });
+      const url2 = await clientNoCache.getDownloadURL({ path: key });
+
+      // Without cache, new URLs might be generated each time
+      // Both should be valid URLs
+      expect(url1).toMatch(
+        /^http:\/\/localhost:9000\/geekmidas\/test-files\/no-cache\.txt/,
+      );
+      expect(url2).toMatch(
+        /^http:\/\/localhost:9000\/geekmidas\/test-files\/no-cache\.txt/,
+      );
+    });
+
+    it('should pass cache to constructor', () => {
+      const cache = new InMemoryCache<string>();
+      const s3Client = new S3Client({
+        region: 'us-east-1',
+        credentials: {
+          accessKeyId: 'geekmidas',
+          secretAccessKey: 'geekmidas',
+        },
+        endpoint: 'http://localhost:9000',
+        forcePathStyle: true,
+      });
+
+      const clientWithCache = new AmazonStorageClient(
+        s3Client,
+        testBucket,
+        AmazonCannedAccessControlList.PublicRead,
+        cache,
+      );
+
+      expect(clientWithCache.cache).toBe(cache);
+    });
+  });
+
+  describe('getVersionDownloadURL', () => {
+    it('should generate version-specific download URL', async () => {
+      const versionKey = 'test-files/version-download.txt';
+      const versionId = 'test-version-id';
+
+      // Upload a file first
+      await client.upload(versionKey, testContent, testContentType);
+
+      // Generate version-specific download URL
+      const downloadUrl = await client.getVersionDownloadURL(
+        { path: versionKey, name: 'versioned-file.txt' },
+        versionId,
+      );
+
+      expect(downloadUrl).toMatch(
+        /^http:\/\/localhost:9000\/geekmidas\/test-files\/version-download\.txt/,
+      );
+      expect(downloadUrl).toContain('X-Amz-Algorithm=AWS4-HMAC-SHA256');
+      expect(downloadUrl).toContain(
+        'response-content-disposition=attachment%3B%20filename%3Dversioned-file.txt',
+      );
+    });
+
+    it('should generate version URL without filename', async () => {
+      const versionKey = 'test-files/version-no-name.txt';
+      const versionId = 'test-version-id';
+
+      // Upload a file first
+      await client.upload(versionKey, testContent, testContentType);
+
+      // Generate version-specific download URL without filename
+      const downloadUrl = await client.getVersionDownloadURL(
+        { path: versionKey },
+        versionId,
+      );
+
+      expect(downloadUrl).toMatch(
+        /^http:\/\/localhost:9000\/geekmidas\/test-files\/version-no-name\.txt/,
+      );
+      expect(downloadUrl).not.toContain('response-content-disposition');
+    });
+  });
 });