offline-cloudinary 2.0.0 → 2.1.1

package/CHANGELOG.md

@@ -5,6 +5,38 @@ 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.1] - 2026-01-15
+
+### Fixed
+
+- Fixed file path resolution in `viewImage` controller to properly use cached file paths
+- Ensured in-memory cache is explicitly loaded from disk on server startup via `initialise()` call
+
+## [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
@@ -62,7 +94,7 @@ const result = await offlineCloudinary.upload("./photo.jpg");
 const result = await offlineCloudinary.upload("./photo.jpg");
 // result.public_id is now a UUID like "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
 // result.url is "http://localhost:3000/file/a1b2c3d4-e5f6-7890-abcd-ef1234567890"
-// result.secure_url is the actual file path
+// result.secure_url is "http://localhost:3000/file/a1b2c3d4-e5f6-7890-abcd-ef1234567890"
 ```
 
 #### 4. Update destroy calls

package/index.js

@@ -9,12 +9,18 @@ app.use(cors());
 
 app.use("/file", fileRoutes);
 
-const startEmulator = () => {
+const startEmulator = async() => {
   const portNumber = process.env.CLOUDINARY_OFFLINE_PORT;
   if (!portNumber)
     throw new Error("Please set CLOUDINARY_OFFLINE_PORT in your .env file");
-  app.listen(portNumber, () =>
+  await offlineCloudinary.initialise()
+  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.1",
   "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/controllers/fileControllers.js

@@ -1,10 +1,8 @@
 import offlineCloudinary from '../utils/offline-cloudinary.js';
-import fs from 'fs/promises';
 
 export const viewImage = async(req, res)=>{
     const uploadId = req.params.id
-    const data = await fs.readFile("uploads.json", "utf-8")
-    const mappings = JSON.parse(data)
+    const mappings = offlineCloudinary.mappingsInMemory
     res.setHeader("Content-Disposition", "inline")
-    return res.sendFile(`${offlineCloudinary.rootPath}/${mappings[uploadId]}`)
+    return res.sendFile(`${mappings[uploadId]}`)
 }

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,7 @@ 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");
+    const portNumber = process.env.CLOUDINARY_OFFLINE_PORT || 3500;
     await fs.access(tempFilePath).catch(() => {
       throw new Error(`File not found: ${tempFilePath}`);
     });
@@ -47,12 +68,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 {
@@ -84,9 +101,12 @@ class OfflineCloudinary {
    */
   async destroy(public_id) {
     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 +117,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" };
   }
 }

package/src/utils/uploads.json

@@ -1 +0,0 @@
-{}