offline-cloudinary 2.0.0 → 2.1.0

package/CHANGELOG.md

@@ -5,6 +5,31 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.1.0] - 2025-12-18
+
+### Added
+
+- **In-memory caching system**: File mappings are now cached in memory for dramatically faster operations
+- **Dirty flag tracking**: Efficient cache invalidation system that only syncs to disk when changes occur
+- **Automatic periodic sync**: Background task (500ms intervals) automatically persists cache changes to disk
+- **Graceful shutdown**: Process cleanup handler that ensures all in-memory changes are synced to disk on exit
+
+### Changed
+
+- `upload()` and `destroy()` operations now use in-memory cache for improved performance
+- `initialise()` method now handles lazy initialization and cache management
+- Improved resource management with automatic interval cleanup
+
+### Performance
+
+- Significantly reduced disk I/O operations
+- Faster file operations through in-memory lookups
+- Minimal overhead with periodic batch writes to disk
+
+### Fully Backward Compatible
+
+All v2.0.0 APIs remain unchanged. The caching system is transparent to end users.
+
 ## [2.0.0] - 2025-12-15
 
 ### Breaking Changes

package/index.js

@@ -13,8 +13,13 @@ const startEmulator = () => {
   const portNumber = process.env.CLOUDINARY_OFFLINE_PORT;
   if (!portNumber)
     throw new Error("Please set CLOUDINARY_OFFLINE_PORT in your .env file");
-  app.listen(portNumber, () =>
+  app.listen(portNumber, () =>{
     console.log("Offline Cloudinary running on port", portNumber)
+    process.on("SIGINT", async()=>{
+      if (offlineCloudinary.syncActive) clearInterval(offlineCloudinary.syncActive)
+      await offlineCloudinary.syncToDisk()
+    })
+  }
   );
 };
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "offline-cloudinary",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "An offline Cloudinary-like file manager with HTTP server emulator for local uploads, deletions, and testing without internet access.",
   "main": "index.js",
   "type": "module",

package/src/utils/offline-cloudinary.js

@@ -8,6 +8,29 @@ class OfflineCloudinary {
       throw new Error("Please set CLOUDINARY_OFFLINE_PATH in your .env file");
     }
     this.rootPath = process.env.CLOUDINARY_OFFLINE_PATH;
+    this.initialised = false;
+    this.mappingsInMemory = { isDirty: false };
+    this.syncActive = false;
+  }
+
+  async initialise() {
+    if (this.initialised) return;
+    const filePath = path.join(this.rootPath, "uploads.json");
+    await fs.access(filePath).catch(() => fs.writeFile(filePath, "{}"));
+    const data = await fs.readFile(filePath, "utf-8");
+    this.mappingsInMemory = { ...JSON.parse(data), isDirty: false };
+    this.initialised = true;
+    this.syncActive = setInterval(() => this.syncToDisk(), 500);
+  }
+
+  async syncToDisk() {
+    if (!this.mappingsInMemory.isDirty) return;
+    const mappingsCopy = { ...this.mappingsInMemory, isDirty: false };
+    await fs.writeFile(
+      path.join(this.rootPath, "uploads.json"),
+      JSON.stringify(mappingsCopy)
+    );
+    this.mappingsInMemory.isDirty = false;
   }
 
   /**
@@ -17,9 +40,8 @@ class OfflineCloudinary {
    * @returns Cloudinary-like response
    */
   async upload(tempFilePath, options = {}) {
-    const portNumber = process.env.CLOUDINARY_OFFLINE_PORT;
-    if (!portNumber)
-      throw new Error("Please set CLOUDINARY_OFFLINE_PORT in your .env file");
+    await this.initialise();
+    const portNumber = process.env.CLOUDINARY_OFFLINE_PORT || 3500;
     await fs.access(tempFilePath).catch(() => {
       throw new Error(`File not found: ${tempFilePath}`);
     });
@@ -47,12 +69,8 @@ class OfflineCloudinary {
 
     const uploadId = crypto.randomUUID();
 
-    const data = await fs.readFile("uploads.json", "utf-8");
-
-    const mappings = JSON.parse(data);
-    mappings[uploadId] = finalPath;
-
-    await fs.writeFile("uploads.json", JSON.stringify(mappings));
+    this.mappingsInMemory[uploadId] = finalPath;
+    this.mappingsInMemory.isDirty = true;
 
     // Return Cloudinary-like response
     return {
@@ -83,10 +101,14 @@ class OfflineCloudinary {
    * @returns {object} { result: "ok" } if deleted or { result: "not found" }
    */
   async destroy(public_id) {
+    await this.initialise();
     const uploadId = public_id;
-    const data = await fs.readFile("uploads.json", "utf-8");
-    const mappings = JSON.parse(data);
-    await fs.unlink(mappings[uploadId]);
+    const filePath = this.mappingsInMemory[uploadId];
+    if (filePath) {
+      await fs.unlink(filePath);
+      delete this.mappingsInMemory[uploadId];
+      this.mappingsInMemory.isDirty = true;
+    }
     return { result: "ok" };
   }
 
@@ -97,6 +119,7 @@ class OfflineCloudinary {
   async clearStorage() {
     await fs.rm(this.rootPath, { recursive: true, force: true });
     await fs.mkdir(this.rootPath);
+    this.mappingsInMemory = { isDirty: false };
     return { result: "ok" };
   }
 }