image-utility-library/README.md

A Node.js library for compressing, resizing, cropping, and applying effects to images.

---


# 📸 **Image Utility Library**

A powerful, lightweight image processing library for Node.js. Easily compress, crop, resize, convert formats, apply effects, and export images in bulk with high performance.

---


### 🚀 **Features**

- ✅ **Image Compression** – Reduce file sizes while maintaining quality  
- ✂️ **Cropping** – Crop images to specific dimensions  
- 📏 **Resizing** – Resize images to custom dimensions  
- 🎨 **Format Conversion** – Convert images between formats (JPEG, PNG, WebP)  
- 🌈 **Effects** – Apply effects like grayscale, invert, and sepia  
- ⚡ **Caching** – Cache frequently processed images for faster performance  
- 📦 **ZIP Export** – Export multiple processed images into a ZIP archive  

---


### 📦 **Installation**

Install the library using NPM:

```bash
npm install image-utility-lib
```

---


### 📂 **Usage**

First, import the functions into your project:

#### **CommonJS**
```js
const {
  compressImage,
  cropImage,
  resizeImage,
  formatImage,
  applyEffects,
  cacheImage,
  getCachedImage,
  exportAsZip
} = require('image-utility-lib');
```

#### **ES6**
```js
import {
  compressImage,
  cropImage,
  resizeImage,
  formatImage,
  applyEffects,
  cacheImage,
  getCachedImage,
  exportAsZip
} from 'image-utility-lib';
```

---


### ➡️ **Examples**

#### 📉 **1. Compress an Image**

```js
const fs = require('fs');

const imageBuffer = fs.readFileSync('input.jpg');

compressImage(imageBuffer, 50).then((compressed) => {
  fs.writeFileSync('output-compressed.jpg', compressed);
});
```

---


#### ✂️ **2. Crop an Image**

```js
cropImage(imageBuffer, 300, 300).then((cropped) => {
  fs.writeFileSync('output-cropped.jpg', cropped);
});
```

---


#### 📏 **3. Resize an Image**

```js
resizeImage(imageBuffer, 800, 600).then((resized) => {
  fs.writeFileSync('output-resized.jpg', resized);
});
```

---


#### 🖼️ **4. Convert Image Format**

```js
formatImage(imageBuffer, 'png').then((converted) => {
  fs.writeFileSync('output-converted.png', converted);
});
```

---


#### 🎨 **5. Apply Effects**

```js
applyEffects(imageBuffer, 'sepia').then((effectApplied) => {
  fs.writeFileSync('output-sepia.jpg', effectApplied);
});
```

Available effects:
- `grayscale`
- `invert`
- `sepia`

---


#### ⚡ **6. Cache Processed Images**

```js
cacheImage('unique-key', compressed);

// Retrieve cached image
const cachedImage = getCachedImage('unique-key');
if (cachedImage) {
  console.log('Image retrieved from cache!');
}
```

---


#### 📦 **7. Export Images as ZIP**

```js
exportAsZip(
  [
    { name: 'compressed.jpg', buffer: compressed },
    { name: 'resized.jpg', buffer: resized }
  ],
  'output-images.zip'
).then(() => {
  console.log('Images exported as ZIP successfully!');
});
```

---


### 📋 **API Reference**

#### 🔥 **Image Processing Functions**

##### `compressImage(imageBuffer, quality) → Promise<Buffer>`
- **imageBuffer**: `Buffer` – The input image data  
- **quality**: `Number` – Compression quality (1–100)

##### `cropImage(imageBuffer, width, height) → Promise<Buffer>`
- **width**: `Number` – Width of the cropped area  
- **height**: `Number` – Height of the cropped area  

##### `resizeImage(imageBuffer, width, height) → Promise<Buffer>`
- **width**: `Number` – New width  
- **height**: `Number` – New height  

##### `formatImage(imageBuffer, format) → Promise<Buffer>`
- **format**: `String` – Target format (`jpeg`, `png`, `webp`)  

##### `applyEffects(imageBuffer, effect) → Promise<Buffer>`
- **effect**: `String` – Image effect (`grayscale`, `invert`, `sepia`)  

---


#### ⚡ **Caching Functions**

##### `cacheImage(key, imageBuffer)`
- **key**: `String` – Unique identifier for caching  
- **imageBuffer**: `Buffer` – The processed image to store  

##### `getCachedImage(key) → Buffer|null`
- Retrieves an image from the cache, if available  

---


#### 📦 **Export Functions**

##### `exportAsZip(images, outputPath) → Promise<void>`
- **images**: `Array` – List of `{ name: String, buffer: Buffer }` objects  
- **outputPath**: `String` – Output path for the ZIP file  

---


### 🛠️ **Requirements**
- Node.js **v14+**  
- Supported formats: **JPEG**, **PNG**, **WebP**

---


### 🐛 **Contributing**

1. Fork the repository  
2. Create a new branch (`git checkout -b feature/your-feature`)  
3. Commit your changes (`git commit -m 'Add new feature'`)  
4. Push to the branch (`git push origin feature/your-feature`)  
5. Open a pull request 🚀  

---


### 📜 **License**
This project is licensed under the **MIT License**.

---


### 👨‍💻 **Author**
Developed by [Ayushman Gupta](https://github.com/your-username) 🚀  

---


### 🙌 **Acknowledgments**
- Built using **sharp**, **jimp**, **imagemin**, and **node-cache**.  
- Inspired by the need for an efficient and versatile image utility library.

---