offline-cloudinary 1.0.0 → 2.1.0

package/CHANGELOG.md

@@ -0,0 +1,115 @@
+# Changelog
+
+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
+
+- **Main export location changed**: Moved from `src/index.js` to root `index.js`
+- **Port configuration**: Now requires `CLOUDINARY_OFFLINE_PORT` environment variable
+- **Public ID format**: `public_id` is now a UUID instead of a file path
+- **Upload response URL**: The `url` field now returns an HTTP endpoint (`http://localhost:PORT/file/{id}`) instead of a file path
+- **Secure URL**: The `secure_url` field also now returns an HTTP endpoint (`http://localhost:PORT/file/{id}`) instead of a file path
+
+### Added
+
+- **HTTP Server Emulator**: New `startEmulator()` function to run a local Express server that serves uploaded files
+- **File viewing endpoint**: GET `/file/:id` endpoint to view/download uploaded files via HTTP
+- **Upload tracking**: Internal `uploads.json` file maps UUIDs to file paths
+- **New environment variable**: `CLOUDINARY_OFFLINE_PORT` for configuring the server port
+- **Express integration**: Built-in CORS and Express routing support
+
+### Changed
+
+- File tracking now uses a JSON mapping file (`uploads.json`) instead of direct file paths
+- Upload method now generates UUID-based public IDs for better privacy and consistency
+- Files can now be accessed via HTTP URLs when the emulator is running
+
+### Migration Guide from v1.x to v2.x
+
+#### 1. Update your `.env` file
+
+Add the new port configuration:
+
+```env
+CLOUDINARY_OFFLINE_PATH=./offline_uploads
+CLOUDINARY_OFFLINE_PORT=3000
+```
+
+#### 2. Start the emulator
+
+```js
+import { startEmulator, offlineCloudinary } from "offline-cloudinary";
+
+// Start the HTTP server
+startEmulator();
+```
+
+#### 3. Update public_id handling
+
+**Before (v1):**
+```js
+const result = await offlineCloudinary.upload("./photo.jpg");
+// result.public_id was a file path like "./offline_uploads/photo.jpg"
+```
+
+**After (v2):**
+```js
+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
+```
+
+#### 4. Update destroy calls
+
+Use the UUID from upload response:
+
+```js
+const uploadResult = await offlineCloudinary.upload("./photo.jpg");
+await offlineCloudinary.destroy(uploadResult.public_id); // Pass the UUID
+```
+
+---
+
+## [1.0.0] - Initial Release
+
+### Added
+
+- Initial release with basic upload, delete, and clearStorage functionality
+- Environment-based path configuration via `CLOUDINARY_OFFLINE_PATH`
+- Cloudinary-like response format
+- Support for nested folder structures
+- Custom filename option
+
+[2.0.0]: https://github.com/MaxEssien/offline-cloudinary/compare/v1.0.0...v2.0.0
+[1.0.0]: https://github.com/MaxEssien/offline-cloudinary/releases/tag/v1.0.0

package/README.md

@@ -6,9 +6,10 @@ An **offline Cloudinary-like file manager** for Node.js — designed for develop
 
 ## Features
 
-- Local file uploads and deletions  
+- Local file uploads and deletions with HTTP server emulator
 - Cloudinary-style API responses  
 - Simple environment-based configuration  
+- Built-in Express server to serve uploaded files via HTTP
 - Clear all stored uploads with one command  
 - Perfect for testing, prototyping, or offline development  
 
@@ -30,20 +31,25 @@ yarn add offline-cloudinary
 
 ## Setup
 
-In your project’s `.env` file, define the base path for all offline uploads:
+In your project's `.env` file, define the configuration for offline uploads:
 
-```
+```env
 CLOUDINARY_OFFLINE_PATH=./offline_uploads
+CLOUDINARY_OFFLINE_PORT=3000
 ```
 
-This path will serve as your “offline cloud” — all uploaded files will be stored here.
+- **`CLOUDINARY_OFFLINE_PATH`**: Base directory where uploaded files will be stored
+- **`CLOUDINARY_OFFLINE_PORT`**: Port number for the HTTP server emulator
 
 ---
 
-## Usage Example
+## Quick Start
 
 ```js
-import offlineCloudinary from "offline-cloudinary";
+import { startEmulator, offlineCloudinary } from "offline-cloudinary";
+
+// Start the HTTP server to serve uploaded files
+startEmulator();
 
 (async () => {
   try {
@@ -54,6 +60,11 @@ import offlineCloudinary from "offline-cloudinary";
     });
 
     console.log("Upload result:", uploadResult);
+    // uploadResult.url: "http://localhost:3000/file/{uuid}"
+    // uploadResult.public_id: UUID identifier
+
+    // Access the file via HTTP
+    console.log(`View file at: ${uploadResult.url}`);
 
     // Delete the uploaded file
     const deleteResult = await offlineCloudinary.destroy(uploadResult.public_id);
@@ -72,16 +83,39 @@ import offlineCloudinary from "offline-cloudinary";
 
 ## API Reference
 
-### **`new OfflineCloudinary()`**
-Automatically instantiated when imported.  
+### **`startEmulator()`**
+
+Starts the Express HTTP server to serve uploaded files.
+
+**Important**: Must be called to enable HTTP access to uploaded files via the `url` field.
+
+**Environment Variables Required:**
+- `CLOUDINARY_OFFLINE_PORT` - Port number for the server
+
+**Example:**
+```js
+import { startEmulator } from "offline-cloudinary";
+
+startEmulator();
+// Server running on port specified in CLOUDINARY_OFFLINE_PORT
+```
+
+---
+
+### **`offlineCloudinary`**
+
+The main instance for file operations. Automatically instantiated when imported.  
 Throws an error if `CLOUDINARY_OFFLINE_PATH` is not set.
 
 ---
 
-### **`upload(tempFilePath, options)`**
+### **`offlineCloudinary.upload(tempFilePath, options)`**
 
 Uploads a file from a temporary path to your offline storage.
 
+**Environment Variables Required:**
+- `CLOUDINARY_OFFLINE_PORT` - Used to generate the HTTP URL
+
 **Parameters**
 | Name | Type | Description |
 |------|------|--------------|
@@ -90,33 +124,67 @@ Uploads a file from a temporary path to your offline storage.
 | `options.fileName` | `string` | Optional custom file name (without extension) |
 
 **Returns**
+
 A Cloudinary-like object containing:
 ```js
 {
-  asset_id, public_id, version, format, resource_type,
-  created_at, bytes, url, secure_url, ...
+  asset_id: "uuid-v4",
+  public_id: "uuid-v4",           // UUID identifier for this file
+  version: 1702654321000,          // Timestamp
+  version_id: "uuid-v4",
+  signature: "hex-string",
+  width: null,
+  height: null,
+  format: "jpg",                   // File extension
+  resource_type: "image",
+  created_at: "2025-12-15T10:30:00.000Z",
+  tags: [],
+  pages: 1,
+  bytes: 102400,                   // File size in bytes
+  type: "upload",
+  etag: "hex-string",
+  placeholder: false,
+  url: "http://localhost:3000/file/{uuid}",      // HTTP URL to access file
+  secure_url: "/path/to/actual/file.jpg"         // Actual file system path
 }
 ```
 
+**Example:**
+```js
+const result = await offlineCloudinary.upload("./photo.jpg", {
+  folder: "users/avatars",
+  fileName: "profile-pic"
+});
+
+console.log(result.url);        // "http://localhost:3000/file/abc123..."
+console.log(result.public_id);  // "abc123-def456-789..."
+```
+
 ---
 
-### **`destroy(public_id)`**
+### **`offlineCloudinary.destroy(public_id)`**
 
-Deletes a file from your offline storage.
+Deletes a file from your offline storage using its UUID.
 
 **Parameters**
 | Name | Type | Description |
 |------|------|--------------|
-| `public_id` | `string` | Full path returned by the upload method |
+| `public_id` | `string` | UUID returned by the upload method |
 
 **Returns**
 ```js
 { result: "ok" }
 ```
 
+**Example:**
+```js
+const uploadResult = await offlineCloudinary.upload("./photo.jpg");
+await offlineCloudinary.destroy(uploadResult.public_id);
+```
+
 ---
 
-### **`clearStorage()`**
+### **`offlineCloudinary.clearStorage()`**
 
 Deletes all files and folders in your offline Cloudinary storage.
 
@@ -125,12 +193,19 @@ Deletes all files and folders in your offline Cloudinary storage.
 { result: "ok" }
 ```
 
+**Example:**
+```js
+await offlineCloudinary.clearStorage();
+console.log("All files deleted");
+```
+
 ---
 
 ## Example .env
 
-```
+```env
 CLOUDINARY_OFFLINE_PATH=./uploads
+CLOUDINARY_OFFLINE_PORT=3000
 ```
 
 ---
@@ -140,6 +215,7 @@ CLOUDINARY_OFFLINE_PATH=./uploads
 ```
 project/
 ├── .env
+├── uploads.json                    # Auto-generated UUID mapping
 ├── uploads/
 │   └── users/
 │       └── avatars/
@@ -149,6 +225,42 @@ project/
 
 ---
 
+## Migration from v1.x to v2.x
+
+### Breaking Changes
+
+1. **New environment variable required**: `CLOUDINARY_OFFLINE_PORT`
+2. **Import changed**: Now exports `{ startEmulator, offlineCloudinary }` instead of default export
+3. **public_id format**: Now returns UUID instead of file path
+4. **URL field**: Now returns HTTP endpoint instead of file path
+5. **Must call startEmulator()** to serve files via HTTP
+
+### Migration Steps
+
+**Before (v1.x):**
+```js
+import offlineCloudinary from "offline-cloudinary";
+
+const result = await offlineCloudinary.upload("./photo.jpg");
+// result.public_id was a file path
+```
+
+**After (v2.x):**
+```js
+import { startEmulator, offlineCloudinary } from "offline-cloudinary";
+
+// Add CLOUDINARY_OFFLINE_PORT=3000 to your .env
+
+startEmulator(); // Start the HTTP server
+
+const result = await offlineCloudinary.upload("./photo.jpg");
+// result.public_id is now a UUID
+// result.url is "http://localhost:3000/file/{uuid}"
+// result.secure_url is "http://localhost:3000/file/{uuid}"
+```
+
+---
+
 ## Author
 
 **Max Essien**  
@@ -162,5 +274,12 @@ project/
 This project is licensed under the **MIT License** — free for personal and commercial use.
 
 ---
+
+## Changelog
+
+See [CHANGELOG.md](./CHANGELOG.md) for version history and migration guides.
+
+---
+
 **Offline Cloudinary** — your Cloudinary, anywhere, even offline.
 

package/index.js

@@ -0,0 +1,26 @@
+import express from "express";
+import fileRoutes from "./src/routes/fileRoutes.js";
+import offlineCloudinary from "./src/utils/offline-cloudinary";
+import cors from "cors";
+
+const app = express();
+
+app.use(cors());
+
+app.use("/file", fileRoutes);
+
+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, () =>{
+    console.log("Offline Cloudinary running on port", portNumber)
+    process.on("SIGINT", async()=>{
+      if (offlineCloudinary.syncActive) clearInterval(offlineCloudinary.syncActive)
+      await offlineCloudinary.syncToDisk()
+    })
+  }
+  );
+};
+
+export { startEmulator, offlineCloudinary };

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "offline-cloudinary",
-  "version": "1.0.0",
-  "description": "An offline Cloudinary-like file manager for local uploads and deletions.",
-  "main": "src/utils/OfflineCloudinary.js",
+  "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",
   "keywords": [
     "cloudinary",
@@ -12,7 +12,12 @@
     "mock",
     "testing",
     "file-system",
-    "nodejs"
+    "nodejs",
+    "express",
+    "server",
+    "emulator",
+    "http",
+    "file-upload"
   ],
   "author": "Max Essien",
   "license": "MIT",
@@ -20,12 +25,25 @@
     "type": "git",
     "url": "https://github.com/MaxEssien/offline-cloudinary"
   },
-  "files": ["src"],
+  "files": [
+    "src",
+    "index.js",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
   "scripts": {
-    "test": "node src/utils/OfflineCloudinary.js"
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "engines": {
+    "node": ">=18.0.0"
   },
   "bugs": {
     "url": "https://github.com/MaxEssien/offline-cloudinary/issues"
   },
-  "homepage": "https://github.com/MaxEssien/offline-cloudinary#readme"
+  "homepage": "https://github.com/MaxEssien/offline-cloudinary#readme",
+  "dependencies": {
+    "cors": "^2.8.5",
+    "express": "^5.2.1"
+  }
 }

package/src/controllers/fileControllers.js

@@ -0,0 +1,10 @@
+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)
+    res.setHeader("Content-Disposition", "inline")
+    return res.sendFile(`${offlineCloudinary.rootPath}/${mappings[uploadId]}`)
+}

package/src/routes/fileRoutes.js

@@ -0,0 +1,8 @@
+import express from "express";
+import { viewImage } from "../controllers/fileControllers.js";
+
+const router = express.Router()
+
+router.get("/:id", viewImage)
+
+export default router

package/src/utils/offline-cloudinary.js

@@ -0,0 +1,129 @@
+import fs from "fs/promises";
+import path from "path";
+import crypto from "crypto";
+
+class OfflineCloudinary {
+  constructor() {
+    if (!process.env.CLOUDINARY_OFFLINE_PATH) {
+      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;
+  }
+
+  /**
+   * Upload a file
+   * @param {string} tempFilePath - Path to the temporary file
+   * @param {object} options - { folder: 'nested/folder/path' }
+   * @returns Cloudinary-like response
+   */
+  async upload(tempFilePath, options = {}) {
+    await this.initialise();
+    const portNumber = process.env.CLOUDINARY_OFFLINE_PORT || 3500;
+    await fs.access(tempFilePath).catch(() => {
+      throw new Error(`File not found: ${tempFilePath}`);
+    });
+    const folder = options.folder || "";
+    const name = options?.fileName || crypto.randomUUID();
+    const fullFolderPath = path.join(this.rootPath, folder);
+
+    // Ensure folder exists
+    await fs.mkdir(fullFolderPath, { recursive: true });
+
+    // Generate unique filename
+    const ext = path.extname(tempFilePath);
+    if (!ext?.trim()) throw new Error("Unsupported file type");
+    const fileName = name + ext;
+
+    const finalPath = path.join(fullFolderPath, fileName);
+
+    // Copy file from temp path
+    await fs.copyFile(tempFilePath, finalPath);
+
+    // Get file stats
+    const stats = await fs.stat(finalPath);
+
+    const now = new Date().toISOString();
+
+    const uploadId = crypto.randomUUID();
+
+    this.mappingsInMemory[uploadId] = finalPath;
+    this.mappingsInMemory.isDirty = true;
+
+    // Return Cloudinary-like response
+    return {
+      asset_id: crypto.randomUUID(),
+      public_id: uploadId,
+      version: Date.now(),
+      version_id: crypto.randomUUID(),
+      signature: crypto.randomBytes(16).toString("hex"),
+      width: null,
+      height: null,
+      format: ext.replace(".", ""),
+      resource_type: "image",
+      created_at: now,
+      tags: [],
+      pages: 1,
+      bytes: stats.size,
+      type: "upload",
+      etag: crypto.randomBytes(8).toString("hex"),
+      placeholder: false,
+      url: `http://localhost:${portNumber}/file/${uploadId}`,
+      secure_url: `http://localhost:${portNumber}/file/${uploadId}`,
+    };
+  }
+
+  /**
+   * Destroy a file by public_id
+   * @param {string} public_id
+   * @returns {object} { result: "ok" } if deleted or { result: "not found" }
+   */
+  async destroy(public_id) {
+    await this.initialise();
+    const uploadId = public_id;
+    const filePath = this.mappingsInMemory[uploadId];
+    if (filePath) {
+      await fs.unlink(filePath);
+      delete this.mappingsInMemory[uploadId];
+      this.mappingsInMemory.isDirty = true;
+    }
+    return { result: "ok" };
+  }
+
+  /**
+   * Destroy every files and folder in the local offline cloudinary storage
+   * @returns {object} {result: ok} if successful
+   */
+  async clearStorage() {
+    await fs.rm(this.rootPath, { recursive: true, force: true });
+    await fs.mkdir(this.rootPath);
+    this.mappingsInMemory = { isDirty: false };
+    return { result: "ok" };
+  }
+}
+
+const offlineCloudinary = new OfflineCloudinary();
+
+export default offlineCloudinary;

package/src/utils/uploads.json

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

package/src/index.js

@@ -1,92 +0,0 @@
-import fs from "fs/promises";
-import path from "path";
-import crypto from "crypto";
-
-class OfflineCloudinary {
-  constructor() {
-    if (!process.env.CLOUDINARY_OFFLINE_PATH) {
-      throw new Error(
-        "Please set CLOUDINARY_OFFLINE_PATH in your .env file"
-      );
-    }
-    this.rootPath = process.env.CLOUDINARY_OFFLINE_PATH;
-  }
-
-  /**
-   * Upload a file
-   * @param {string} tempFilePath - Path to the temporary file
-   * @param {object} options - { folder: 'nested/folder/path' }
-   * @returns Cloudinary-like response
-   */
-  async upload(tempFilePath, options = {}) {
-    await fs.access(tempFilePath).catch(()=>{throw new Error(`File not found: ${tempFilePath}`)})
-    const folder = options.folder || "";
-    const name = options?.fileName || crypto.randomUUID();
-    const fullFolderPath = path.join(this.rootPath, folder);
-
-    // Ensure folder exists
-    await fs.mkdir(fullFolderPath, { recursive: true });
-
-    // Generate unique filename
-    const ext = path.extname(tempFilePath);
-    if (!ext?.trim()) throw new Error("Unsupported file type")
-    const fileName = name + ext;
-
-    const finalPath = path.join(fullFolderPath, fileName);
-
-    // Copy file from temp path
-    await fs.copyFile(tempFilePath, finalPath);
-
-    // Get file stats
-    const stats = await fs.stat(finalPath);
-
-    const now = new Date().toISOString();
-
-    // Return Cloudinary-like response
-    return {
-      asset_id: crypto.randomUUID(),
-      public_id: finalPath,
-      version: Date.now(),
-      version_id: crypto.randomUUID(),
-      signature: crypto.randomBytes(16).toString("hex"),
-      width: null,
-      height: null,
-      format: ext.replace(".", ""),
-      resource_type: "image",
-      created_at: now,
-      tags: [],
-      pages: 1,
-      bytes: stats.size,
-      type: "upload",
-      etag: crypto.randomBytes(8).toString("hex"),
-      placeholder: false,
-      url: finalPath,
-      secure_url: finalPath,
-    };
-  }
-
-  /**
-   * Destroy a file by public_id
-   * @param {string} public_id
-   * @returns {object} { result: "ok" } if deleted or { result: "not found" }
-   */
-  async destroy(public_id) {
-    const filePath = public_id;
-    await fs.unlink(filePath);
-    return { result: "ok" };
-  }
-
-  /**
-   * Destroy every files and folder in the local offline cloudinary storage
-   * @returns {object} {result: ok} if successful
-   */
-  async clearStorage(){
-    await fs.rm(this.rootPath, {recursive: true, force: true})
-    await fs.mkdir(this.rootPath)
-    return {result: "ok"}
-  }
-}
-
-const offlineCloudinary = new OfflineCloudinary()
-
-export default offlineCloudinary;