v2.2.2

[2.2.2] - 2026-05-27

Added

• Added setRootPath and setPort for high level manipulation in class instance properties
• Added stricter checks for fields methods need with friendly error messages
• Added Mappings syncing and corrupted mappings handling

Changed

• Made upload method options parameter optional

Fixed

• File resource type resolving error

V2.2.0

[2.2.0] - 2026-03-26

Added

• Added TypeScript source layout with new modules in src/ (index.ts, types, and utils/fileHandlers.ts)
• Added richer upload response metadata by probing uploaded files for dimensions (width/height)
• Added resource type detection and validation using file-type

Changed

• Refactored package distribution to compile output in dist/ (main and types now point to dist/index.js and dist/index.d.ts)
• Migrated implementation files from JavaScript to TypeScript and introduced tsconfig.json build pipeline
• Updated dependencies to support metadata probing and type-safe builds (ffprobe, ffprobe-static, file-type, TypeScript tooling)

Fixed

• Improved destroy() behavior to return { result: "not found" } when the file is missing
• Improved clearStorage() to reset in-memory upload mappings after clearing storage

v2.1.3

[2.1.3] - 2026-03-07

Added

• Added TypeScript type declarations (index.d.ts) for full TypeScript support
• Added "types" field to package.json pointing to type definitions

v2.1.2

[2.1.2] - 2026-01-19

Fixed

• Fixed ES module import path in index.js by adding .js extension to offline-cloudinary import for proper CommonJS interoperability

v2.1.1

[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

v2.1.0

[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.

v2.0.0

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog,
and this project adheres to Semantic Versioning.

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:

CLOUDINARY_OFFLINE_PATH=./offline_uploads
CLOUDINARY_OFFLINE_PORT=3000

2. Start the emulator

import { startEmulator, offlineCloudinary } from "offline-cloudinary";

// Start the HTTP server
startEmulator();

3. Update public_id handling

Before (v1):

const result = await offlineCloudinary.upload("./photo.jpg");
// result.public_id was a file path like "./offline_uploads/photo.jpg"

After (v2):

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:

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