@capgo/capacitor-file-compressor 8.0.33 → 8.1.0

package/README.md

@@ -6,15 +6,16 @@
   <h2><a href="https://capgo.app/consulting/?ref=plugin_file-compressor"> Missing a feature? We'll build the plugin for you 💪</a></h2>
 </div>
 
-Capacitor plugin for efficient image compression supporting PNG, JPEG, and WebP formats across iOS, Android, and Web platforms.
+Capacitor plugin for efficient image compression and **format conversion** across iOS, Android, and Web.
 
 ## Why File Compressor?
 
 A free, open-source alternative for **client-side image compression**:
 
-- **Multiple formats** - JPEG and WebP compression support
+- **Format conversion** - Convert HEIF, PNG, WebP, GIF, and more to JPEG, PNG, WebP, or HEIF
+- **Multiple formats** - Broad input support with platform-specific output formats
 - **Quality control** - Adjustable compression quality (0.0 - 1.0)
-- **Smart resizing** - Automatic aspect ratio preservation
+- **Smart resizing** - Automatic aspect ratio preservation without upscaling
 - **Cross-platform** - Consistent API across iOS, Android, and Web
 - **Zero backend** - All compression happens on the device
 
@@ -56,13 +57,28 @@ npm install @capgo/capacitor-file-compressor
 npx cap sync
 ```
 
-## Platform Support
+## Format Conversion
 
-| Platform | Supported Formats | Notes |
-|----------|-------------------|-------|
-| iOS | JPEG | Only JPEG compression supported |
-| Android | JPEG, WebP | Both formats fully supported |
-| Web | JPEG, WebP | Canvas API-based compression |
+The plugin accepts common image formats as input and converts them to the `mimeType` you request.
+
+| Platform | Input formats | Output formats |
+|----------|---------------|----------------|
+| iOS | JPEG, PNG, WebP, GIF, BMP, TIFF, HEIF/HEIC | JPEG, PNG, HEIF/HEIC, WebP (iOS 14+) |
+| Android | JPEG, PNG, WebP, GIF, BMP, HEIF/HEIC (API 28+) | JPEG, PNG, WebP |
+| Web | Any format the browser can decode | JPEG, PNG, WebP |
+
+```typescript
+import { FileCompressor } from '@capgo/capacitor-file-compressor';
+
+// Convert an iPhone HEIF photo to JPEG before upload
+const result = await FileCompressor.compressImage({
+  path: heifFileUri,
+  width: 1920,
+  height: 1080,
+  quality: 0.7,
+  mimeType: 'image/jpeg',
+});
+```
 
 Note: EXIF metadata is removed during compression on all platforms.
 
@@ -90,12 +106,22 @@ compressImage(options: CompressImageOptions) => Promise<CompressImageResult>
 Compresses an image file with specified dimensions and quality settings.
 
 This method compresses images to reduce file size while maintaining acceptable quality.
-It supports resizing and format conversion (JPEG/WebP depending on platform).
+It supports resizing and format conversion across common image formats.
+
+**Supported input formats (platform decoder dependent):**
+JPEG, PNG, WebP, GIF, BMP, TIFF, HEIF/HEIC
+
+**Supported output formats:**
+- **iOS:** `image/jpeg`, `image/png`, `image/heif`, `image/heic`, `image/webp` (iOS 14+)
+- **Android:** `image/jpeg`, `image/png`, `image/webp`
+- **Web:** `image/jpeg`, `image/png`, `image/webp`
 
 **Important Notes:**
 - EXIF metadata is removed during compression on all platforms
 - Aspect ratio is automatically maintained if only one dimension is provided
+- When both width and height are provided, the image fits inside that box without upscaling
 - Compressed files are saved to temporary directories on native platforms
+- If the encoded output would be larger than the source file, quality is reduced automatically while keeping the requested output format
 
 | Param         | Type                                                                  | Description                                   |
 | ------------- | --------------------------------------------------------------------- | --------------------------------------------- |
@@ -149,13 +175,13 @@ Options for compressing an image.
 Configure the compression behavior including quality, dimensions, and output format.
 Platform-specific options are available for path (native) and blob (web).
 
-| Prop           | Type                | Description                                                                                                                                                                                                                                                                                                                                                                                             | Default                   | Since |
-| -------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- | ----- |
-| **`path`**     | <code>string</code> | The file path of the image to compress. **Platform:** Android, iOS only (not supported on Web) Accepts various path formats: - iOS: `file://` URLs or absolute paths - Android: `content://` URIs, `file://` URLs, or absolute paths                                                                                                                                                                    |                           | 7.0.0 |
-| **`blob`**     | <code>Blob</code>   | The file blob of the image to compress. **Platform:** Web only (not supported on iOS/Android) Use this when compressing images from file inputs, fetch responses, or any other Blob source in web applications.                                                                                                                                                                                         |                           | 7.0.0 |
-| **`quality`**  | <code>number</code> | The quality of the compressed image. **Range:** 0.0 to 1.0 - `0.0` = Maximum compression (lowest quality, smallest file) - `1.0` = Minimum compression (highest quality, largest file) - `0.6` = Default balanced compression **Platform:** All platforms Higher quality values result in larger files but better visual quality. The actual compression ratio depends on the image content and format. | <code>0.6</code>          | 7.0.0 |
-| **`width`**    | <code>number</code> | The width of the compressed image in pixels. **Platform:** All platforms If only width is specified, height is calculated automatically to maintain the original aspect ratio. If both width and height are specified, the image is resized to exact dimensions (may distort if ratio differs).                                                                                                         |                           | 7.0.0 |
-| **`height`**   | <code>number</code> | The height of the compressed image in pixels. **Platform:** All platforms If only height is specified, width is calculated automatically to maintain the original aspect ratio. If both width and height are specified, the image is resized to exact dimensions (may distort if ratio differs).                                                                                                        |                           | 7.0.0 |
-| **`mimeType`** | <code>string</code> | The MIME type of the compressed output image. **Platform Support:** - **iOS:** `image/jpeg` only - **Android:** `image/jpeg`, `image/webp` - **Web:** `image/jpeg`, `image/webp` **Format Characteristics:** - **JPEG:** Universal support, good for photos, no transparency - **WebP:** Better compression, supports transparency, not on iOS                                                          | <code>"image/jpeg"</code> | 7.0.0 |
+| Prop           | Type                | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | Default                   | Since |
+| -------------- | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- | ----- |
+| **`path`**     | <code>string</code> | The file path of the image to compress. **Platform:** Android, iOS only (not supported on Web) Accepts various path formats: - iOS: `file://` URLs or absolute paths - Android: `content://` URIs, `file://` URLs, or absolute paths Common input formats include JPEG, PNG, WebP, GIF, BMP, TIFF, and HEIF/HEIC.                                                                                                                                                                                                                                                                                   |                           | 7.0.0 |
+| **`blob`**     | <code>Blob</code>   | The file blob of the image to compress. **Platform:** Web only (not supported on iOS/Android) Use this when compressing images from file inputs, fetch responses, or any other Blob source in web applications.                                                                                                                                                                                                                                                                                                                                                                                     |                           | 7.0.0 |
+| **`quality`**  | <code>number</code> | The quality of the compressed image. **Range:** 0.0 to 1.0 - `0.0` = Maximum compression (lowest quality, smallest file) - `1.0` = Minimum compression (highest quality, largest file) - `0.6` = Default balanced compression **Platform:** All platforms Higher quality values result in larger files but better visual quality. The actual compression ratio depends on the image content and format. PNG output ignores quality because it is lossless.                                                                                                                                          | <code>0.6</code>          | 7.0.0 |
+| **`width`**    | <code>number</code> | The width of the compressed image in pixels. **Platform:** All platforms If only width is specified, height is calculated automatically to maintain the original aspect ratio. If both width and height are specified, the image is scaled to fit inside that box while preserving aspect ratio. Images are never upscaled.                                                                                                                                                                                                                                                                         |                           | 7.0.0 |
+| **`height`**   | <code>number</code> | The height of the compressed image in pixels. **Platform:** All platforms If only height is specified, width is calculated automatically to maintain the original aspect ratio. If both width and height are specified, the image is scaled to fit inside that box while preserving aspect ratio. Images are never upscaled.                                                                                                                                                                                                                                                                        |                           | 7.0.0 |
+| **`mimeType`** | <code>string</code> | The MIME type of the compressed output image. **Platform Support:** - **iOS:** `image/jpeg`, `image/png`, `image/heif`, `image/heic`, `image/webp` (iOS 14+) - **Android:** `image/jpeg`, `image/png`, `image/webp` - **Web:** `image/jpeg`, `image/png`, `image/webp` Use this option to convert the source image to another format while compressing. **Format Characteristics:** - **JPEG:** Universal support, good for photos, no transparency - **PNG:** Lossless, supports transparency - **WebP:** Better compression, supports transparency - **HEIF/HEIC:** Efficient photo format on iOS | <code>"image/jpeg"</code> | 7.0.0 |
 
 </docgen-api>

package/android/src/main/java/io/capgo/filecompressor/FileCompressorPlugin.java

@@ -1,9 +1,9 @@
 package io.capgo.filecompressor;
 
+import android.content.res.AssetFileDescriptor;
 import android.graphics.Bitmap;
 import android.graphics.BitmapFactory;
 import android.net.Uri;
-import android.webkit.MimeTypeMap;
 import com.getcapacitor.JSObject;
 import com.getcapacitor.Plugin;
 import com.getcapacitor.PluginCall;
@@ -13,12 +13,17 @@ import java.io.File;
 import java.io.FileOutputStream;
 import java.io.IOException;
 import java.io.InputStream;
+import java.util.Arrays;
+import java.util.List;
 import java.util.UUID;
 
 @CapacitorPlugin(name = "FileCompressor")
 public class FileCompressorPlugin extends Plugin {
 
-    private final String pluginVersion = "8.0.33";
+    private final String pluginVersion = "8.1.0";
+    private static final float MIN_QUALITY = 0.1f;
+    private static final float QUALITY_STEP = 0.05f;
+    private static final List<String> SUPPORTED_OUTPUT_MIME_TYPES = Arrays.asList("image/jpeg", "image/png", "image/webp");
 
     @PluginMethod
     public void compressImage(PluginCall call) {
@@ -31,56 +36,45 @@ public class FileCompressorPlugin extends Plugin {
         float quality = call.getFloat("quality", 0.6f);
         Integer width = call.getInt("width");
         Integer height = call.getInt("height");
-        String mimeType = call.getString("mimeType", "image/jpeg");
+        String mimeType = call.getString("mimeType", "image/jpeg").toLowerCase();
 
-        // Validate mime type for Android
-        if (!mimeType.equals("image/jpeg") && !mimeType.equals("image/webp")) {
-            call.reject("Only image/jpeg and image/webp are supported on Android");
+        if (!SUPPORTED_OUTPUT_MIME_TYPES.contains(mimeType)) {
+            call.reject("Unsupported output mimeType: " + mimeType + ". Supported: " + String.join(", ", SUPPORTED_OUTPUT_MIME_TYPES));
             return;
         }
 
-        // Validate quality range
         if (quality < 0.0f || quality > 1.0f) {
             call.reject("quality must be between 0.0 and 1.0");
             return;
         }
 
         try {
-            // Load bitmap from path
+            long maxBytes = getOriginalFileSize(path);
+            OutputFormat outputFormat = OutputFormat.fromMimeType(mimeType);
+
             Bitmap bitmap = loadBitmapFromPath(path);
             if (bitmap == null) {
                 call.reject("Failed to load image from path");
                 return;
             }
 
-            // Resize bitmap if dimensions are provided
+            int[] targetDimensions = calculateTargetDimensions(bitmap, width, height);
             Bitmap processedBitmap = bitmap;
-            if (width != null && height != null) {
-                processedBitmap = Bitmap.createScaledBitmap(bitmap, width, height, true);
-            } else if (width != null) {
-                float aspectRatio = (float) bitmap.getHeight() / bitmap.getWidth();
-                int targetHeight = (int) (width * aspectRatio);
-                processedBitmap = Bitmap.createScaledBitmap(bitmap, width, targetHeight, true);
-            } else if (height != null) {
-                float aspectRatio = (float) bitmap.getWidth() / bitmap.getHeight();
-                int targetWidth = (int) (height * aspectRatio);
-                processedBitmap = Bitmap.createScaledBitmap(bitmap, targetWidth, height, true);
+            if (targetDimensions[0] != bitmap.getWidth() || targetDimensions[1] != bitmap.getHeight()) {
+                processedBitmap = Bitmap.createScaledBitmap(bitmap, targetDimensions[0], targetDimensions[1], true);
             }
 
-            // Compress bitmap
-            File compressedFile = compressBitmap(processedBitmap, quality, mimeType);
+            File compressedFile = compressBitmap(processedBitmap, quality, outputFormat, maxBytes);
             if (compressedFile == null) {
                 call.reject("Failed to compress image");
                 return;
             }
 
-            // Clean up
             if (processedBitmap != bitmap) {
                 processedBitmap.recycle();
             }
             bitmap.recycle();
 
-            // Return result
             JSObject result = new JSObject();
             result.put("path", compressedFile.getAbsolutePath());
             call.resolve(result);
@@ -89,9 +83,54 @@ public class FileCompressorPlugin extends Plugin {
         }
     }
 
+    private int[] calculateTargetDimensions(Bitmap bitmap, Integer maxWidth, Integer maxHeight) {
+        int sourceWidth = bitmap.getWidth();
+        int sourceHeight = bitmap.getHeight();
+
+        if (maxWidth == null && maxHeight == null) {
+            return new int[] { sourceWidth, sourceHeight };
+        }
+
+        float ratio = 1f;
+
+        if (maxWidth != null && maxHeight != null) {
+            ratio = Math.min((float) maxWidth / sourceWidth, (float) maxHeight / sourceHeight);
+        } else if (maxWidth != null) {
+            ratio = (float) maxWidth / sourceWidth;
+        } else if (maxHeight != null) {
+            ratio = (float) maxHeight / sourceHeight;
+        }
+
+        ratio = Math.min(ratio, 1f);
+
+        return new int[] { Math.round(sourceWidth * ratio), Math.round(sourceHeight * ratio) };
+    }
+
+    private long getOriginalFileSize(String path) {
+        try {
+            if (path.startsWith("content://")) {
+                Uri uri = Uri.parse(path);
+                try (AssetFileDescriptor descriptor = getContext().getContentResolver().openAssetFileDescriptor(uri, "r")) {
+                    if (descriptor != null) {
+                        return descriptor.getLength();
+                    }
+                }
+            } else {
+                String filePath = path.startsWith("file://") ? path.substring(7) : path;
+                File file = new File(filePath);
+                if (file.exists()) {
+                    return file.length();
+                }
+            }
+        } catch (Exception e) {
+            e.printStackTrace();
+        }
+
+        return -1;
+    }
+
     private Bitmap loadBitmapFromPath(String path) {
         try {
-            // Handle content:// URIs
             if (path.startsWith("content://")) {
                 Uri uri = Uri.parse(path);
                 InputStream inputStream = getContext().getContentResolver().openInputStream(uri);
@@ -100,13 +139,10 @@ public class FileCompressorPlugin extends Plugin {
                     inputStream.close();
                     return bitmap;
                 }
-            }
-            // Handle file:// URIs and absolute paths
-            else if (path.startsWith("file://")) {
-                path = path.substring(7); // Remove "file://" prefix
+            } else if (path.startsWith("file://")) {
+                path = path.substring(7);
             }
 
-            // Try loading as file path
             File file = new File(path);
             if (file.exists()) {
                 return BitmapFactory.decodeFile(file.getAbsolutePath());
@@ -117,29 +153,38 @@ public class FileCompressorPlugin extends Plugin {
         return null;
     }
 
-    private File compressBitmap(Bitmap bitmap, float quality, String mimeType) {
-        try {
-            // Determine compression format and file extension
-            Bitmap.CompressFormat format;
-            String extension;
+    private File compressBitmap(Bitmap bitmap, float quality, OutputFormat outputFormat, long maxBytes) {
+        float currentQuality = quality;
+        File lastFile = null;
 
-            if (mimeType.equals("image/webp")) {
-                format = Bitmap.CompressFormat.WEBP;
-                extension = ".webp";
-            } else {
-                format = Bitmap.CompressFormat.JPEG;
-                extension = ".jpg";
+        while (true) {
+            File compressedFile = writeCompressedBitmap(bitmap, outputFormat, currentQuality);
+            if (compressedFile == null) {
+                return lastFile;
             }
 
-            // Create temporary file
+            if (lastFile != null && lastFile != compressedFile) {
+                lastFile.delete();
+            }
+
+            if (maxBytes <= 0 || compressedFile.length() <= maxBytes || currentQuality <= MIN_QUALITY || !outputFormat.supportsQuality) {
+                return compressedFile;
+            }
+
+            lastFile = compressedFile;
+            currentQuality = Math.max(MIN_QUALITY, currentQuality - QUALITY_STEP);
+        }
+    }
+
+    private File writeCompressedBitmap(Bitmap bitmap, OutputFormat outputFormat, float quality) {
+        try {
             File tempDir = getContext().getCacheDir();
-            String fileName = "compressed_" + UUID.randomUUID().toString() + extension;
+            String fileName = "compressed_" + UUID.randomUUID().toString() + outputFormat.extension;
             File compressedFile = new File(tempDir, fileName);
 
-            // Compress and save
             FileOutputStream outputStream = new FileOutputStream(compressedFile);
-            int qualityInt = (int) (quality * 100);
-            bitmap.compress(format, qualityInt, outputStream);
+            int qualityInt = Math.round(quality * 100);
+            bitmap.compress(outputFormat.format, qualityInt, outputStream);
             outputStream.flush();
             outputStream.close();
 
@@ -160,4 +205,29 @@ public class FileCompressorPlugin extends Plugin {
             call.reject("Could not get plugin version", e);
         }
     }
+
+    private static final class OutputFormat {
+
+        private final Bitmap.CompressFormat format;
+        private final String extension;
+        private final boolean supportsQuality;
+
+        private OutputFormat(Bitmap.CompressFormat format, String extension, boolean supportsQuality) {
+            this.format = format;
+            this.extension = extension;
+            this.supportsQuality = supportsQuality;
+        }
+
+        private static OutputFormat fromMimeType(String mimeType) {
+            switch (mimeType) {
+                case "image/webp":
+                    return new OutputFormat(Bitmap.CompressFormat.WEBP, ".webp", true);
+                case "image/png":
+                    return new OutputFormat(Bitmap.CompressFormat.PNG, ".png", false);
+                case "image/jpeg":
+                default:
+                    return new OutputFormat(Bitmap.CompressFormat.JPEG, ".jpg", true);
+            }
+        }
+    }
 }

package/dist/docs.json

@@ -44,18 +44,18 @@
           },
           {
             "name": "example",
-            "text": "```typescript\n// iOS - Compress image from file path\nconst result = await FileCompressor.compressImage({\n  path: 'file:///var/mobile/Containers/Data/image.jpg',\n  quality: 0.7,\n  width: 1000,\n  mimeType: 'image/jpeg' // Only JPEG supported on iOS\n});\nconsole.log('Compressed to:', result.path);\n```"
+            "text": "```typescript\n// iOS - Convert HEIF iPhone photo to JPEG\nconst result = await FileCompressor.compressImage({\n  path: heifFileUri,\n  quality: 0.7,\n  width: 1920,\n  height: 1080,\n  mimeType: 'image/jpeg'\n});\nconsole.log('Converted to JPEG:', result.path);\n```"
           },
           {
             "name": "example",
-            "text": "```typescript\n// Android - Compress with WebP format\nconst result = await FileCompressor.compressImage({\n  path: 'content://downloads/document/123',\n  quality: 0.6,\n  width: 800,\n  height: 600,\n  mimeType: 'image/webp'\n});\nconsole.log('Compressed to:', result.path);\n```"
+            "text": "```typescript\n// Android - Convert PNG to WebP\nconst result = await FileCompressor.compressImage({\n  path: 'content://downloads/document/123',\n  quality: 0.6,\n  width: 800,\n  height: 600,\n  mimeType: 'image/webp'\n});\nconsole.log('Compressed to:', result.path);\n```"
           },
           {
             "name": "example",
-            "text": "```typescript\n// Maintain aspect ratio - only specify width\nconst result = await FileCompressor.compressImage({\n  path: imagePath,\n  quality: 0.75,\n  width: 1920, // Height calculated automatically\n  mimeType: 'image/jpeg'\n});\n```"
+            "text": "```typescript\n// Maintain aspect ratio - only specify width\nconst result = await FileCompressor.compressImage({\n  path: imagePath,\n  quality: 0.75,\n  width: 1920,\n  mimeType: 'image/jpeg'\n});\n```"
           }
         ],
-        "docs": "Compresses an image file with specified dimensions and quality settings.\n\nThis method compresses images to reduce file size while maintaining acceptable quality.\nIt supports resizing and format conversion (JPEG/WebP depending on platform).\n\n**Important Notes:**\n- EXIF metadata is removed during compression on all platforms\n- Aspect ratio is automatically maintained if only one dimension is provided\n- Compressed files are saved to temporary directories on native platforms",
+        "docs": "Compresses an image file with specified dimensions and quality settings.\n\nThis method compresses images to reduce file size while maintaining acceptable quality.\nIt supports resizing and format conversion across common image formats.\n\n**Supported input formats (platform decoder dependent):**\nJPEG, PNG, WebP, GIF, BMP, TIFF, HEIF/HEIC\n\n**Supported output formats:**\n- **iOS:** `image/jpeg`, `image/png`, `image/heif`, `image/heic`, `image/webp` (iOS 14+)\n- **Android:** `image/jpeg`, `image/png`, `image/webp`\n- **Web:** `image/jpeg`, `image/png`, `image/webp`\n\n**Important Notes:**\n- EXIF metadata is removed during compression on all platforms\n- Aspect ratio is automatically maintained if only one dimension is provided\n- When both width and height are provided, the image fits inside that box without upscaling\n- Compressed files are saved to temporary directories on native platforms\n- If the encoded output would be larger than the source file, quality is reduced automatically while keeping the requested output format",
         "complexTypes": [
           "CompressImageResult",
           "CompressImageOptions"
@@ -117,7 +117,7 @@
               "name": "example"
             },
             {
-              "text": "\"/data/user/0/com.app/cache/compressed_xyz789.jpg\" // Android",
+              "text": "\"/data/user/0/com.app/cache/compressed_xyz789.webp\" // Android",
               "name": "example"
             }
           ],
@@ -169,7 +169,7 @@
               "name": "since"
             },
             {
-              "text": "\"file:///var/mobile/Containers/Data/Application/image.jpg\" // iOS",
+              "text": "\"file:///var/mobile/Containers/Data/Application/photo.heic\" // iOS HEIF",
               "name": "example"
             },
             {
@@ -181,7 +181,7 @@
               "name": "example"
             }
           ],
-          "docs": "The file path of the image to compress.\n\n**Platform:** Android, iOS only (not supported on Web)\n\nAccepts various path formats:\n- iOS: `file://` URLs or absolute paths\n- Android: `content://` URIs, `file://` URLs, or absolute paths",
+          "docs": "The file path of the image to compress.\n\n**Platform:** Android, iOS only (not supported on Web)\n\nAccepts various path formats:\n- iOS: `file://` URLs or absolute paths\n- Android: `content://` URIs, `file://` URLs, or absolute paths\n\nCommon input formats include JPEG, PNG, WebP, GIF, BMP, TIFF, and HEIF/HEIC.",
           "complexTypes": [],
           "type": "string | undefined"
         },
@@ -231,7 +231,7 @@
               "name": "example"
             }
           ],
-          "docs": "The quality of the compressed image.\n\n**Range:** 0.0 to 1.0\n- `0.0` = Maximum compression (lowest quality, smallest file)\n- `1.0` = Minimum compression (highest quality, largest file)\n- `0.6` = Default balanced compression\n\n**Platform:** All platforms\n\nHigher quality values result in larger files but better visual quality.\nThe actual compression ratio depends on the image content and format.",
+          "docs": "The quality of the compressed image.\n\n**Range:** 0.0 to 1.0\n- `0.0` = Maximum compression (lowest quality, smallest file)\n- `1.0` = Minimum compression (highest quality, largest file)\n- `0.6` = Default balanced compression\n\n**Platform:** All platforms\n\nHigher quality values result in larger files but better visual quality.\nThe actual compression ratio depends on the image content and format.\nPNG output ignores quality because it is lossless.",
           "complexTypes": [],
           "type": "number | undefined"
         },
@@ -255,7 +255,7 @@
               "name": "example"
             }
           ],
-          "docs": "The width of the compressed image in pixels.\n\n**Platform:** All platforms\n\nIf only width is specified, height is calculated automatically\nto maintain the original aspect ratio.\n\nIf both width and height are specified, the image is resized\nto exact dimensions (may distort if ratio differs).",
+          "docs": "The width of the compressed image in pixels.\n\n**Platform:** All platforms\n\nIf only width is specified, height is calculated automatically\nto maintain the original aspect ratio.\n\nIf both width and height are specified, the image is scaled to fit inside\nthat box while preserving aspect ratio. Images are never upscaled.",
           "complexTypes": [],
           "type": "number | undefined"
         },
@@ -279,7 +279,7 @@
               "name": "example"
             }
           ],
-          "docs": "The height of the compressed image in pixels.\n\n**Platform:** All platforms\n\nIf only height is specified, width is calculated automatically\nto maintain the original aspect ratio.\n\nIf both width and height are specified, the image is resized\nto exact dimensions (may distort if ratio differs).",
+          "docs": "The height of the compressed image in pixels.\n\n**Platform:** All platforms\n\nIf only height is specified, width is calculated automatically\nto maintain the original aspect ratio.\n\nIf both width and height are specified, the image is scaled to fit inside\nthat box while preserving aspect ratio. Images are never upscaled.",
           "complexTypes": [],
           "type": "number | undefined"
         },
@@ -295,15 +295,23 @@
               "name": "default"
             },
             {
-              "text": "\"image/jpeg\" // JPEG format (all platforms)",
+              "text": "\"image/jpeg\" // JPEG format",
               "name": "example"
             },
             {
-              "text": "\"image/webp\" // WebP format (Android/Web only)",
+              "text": "\"image/png\" // PNG format",
+              "name": "example"
+            },
+            {
+              "text": "\"image/webp\" // WebP format",
+              "name": "example"
+            },
+            {
+              "text": "\"image/heif\" // HEIF format (iOS output)",
               "name": "example"
             }
           ],
-          "docs": "The MIME type of the compressed output image.\n\n**Platform Support:**\n- **iOS:** `image/jpeg` only\n- **Android:** `image/jpeg`, `image/webp`\n- **Web:** `image/jpeg`, `image/webp`\n\n**Format Characteristics:**\n- **JPEG:** Universal support, good for photos, no transparency\n- **WebP:** Better compression, supports transparency, not on iOS",
+          "docs": "The MIME type of the compressed output image.\n\n**Platform Support:**\n- **iOS:** `image/jpeg`, `image/png`, `image/heif`, `image/heic`, `image/webp` (iOS 14+)\n- **Android:** `image/jpeg`, `image/png`, `image/webp`\n- **Web:** `image/jpeg`, `image/png`, `image/webp`\n\nUse this option to convert the source image to another format while compressing.\n\n**Format Characteristics:**\n- **JPEG:** Universal support, good for photos, no transparency\n- **PNG:** Lossless, supports transparency\n- **WebP:** Better compression, supports transparency\n- **HEIF/HEIC:** Efficient photo format on iOS",
           "complexTypes": [],
           "type": "string | undefined"
         }

package/dist/esm/definitions.d.ts

@@ -8,12 +8,22 @@ export interface FileCompressorPlugin {
      * Compresses an image file with specified dimensions and quality settings.
      *
      * This method compresses images to reduce file size while maintaining acceptable quality.
-     * It supports resizing and format conversion (JPEG/WebP depending on platform).
+     * It supports resizing and format conversion across common image formats.
+     *
+     * **Supported input formats (platform decoder dependent):**
+     * JPEG, PNG, WebP, GIF, BMP, TIFF, HEIF/HEIC
+     *
+     * **Supported output formats:**
+     * - **iOS:** `image/jpeg`, `image/png`, `image/heif`, `image/heic`, `image/webp` (iOS 14+)
+     * - **Android:** `image/jpeg`, `image/png`, `image/webp`
+     * - **Web:** `image/jpeg`, `image/png`, `image/webp`
      *
      * **Important Notes:**
      * - EXIF metadata is removed during compression on all platforms
      * - Aspect ratio is automatically maintained if only one dimension is provided
+     * - When both width and height are provided, the image fits inside that box without upscaling
      * - Compressed files are saved to temporary directories on native platforms
+     * - If the encoded output would be larger than the source file, quality is reduced automatically while keeping the requested output format
      *
      * @param options - Configuration options for image compression
      * @returns Promise that resolves with the compressed image path or blob
@@ -34,18 +44,19 @@ export interface FileCompressorPlugin {
      * ```
      * @example
      * ```typescript
-     * // iOS - Compress image from file path
+     * // iOS - Convert HEIF iPhone photo to JPEG
      * const result = await FileCompressor.compressImage({
-     *   path: 'file:///var/mobile/Containers/Data/image.jpg',
+     *   path: heifFileUri,
      *   quality: 0.7,
-     *   width: 1000,
-     *   mimeType: 'image/jpeg' // Only JPEG supported on iOS
+     *   width: 1920,
+     *   height: 1080,
+     *   mimeType: 'image/jpeg'
      * });
-     * console.log('Compressed to:', result.path);
+     * console.log('Converted to JPEG:', result.path);
      * ```
      * @example
      * ```typescript
-     * // Android - Compress with WebP format
+     * // Android - Convert PNG to WebP
      * const result = await FileCompressor.compressImage({
      *   path: 'content://downloads/document/123',
      *   quality: 0.6,
@@ -61,7 +72,7 @@ export interface FileCompressorPlugin {
      * const result = await FileCompressor.compressImage({
      *   path: imagePath,
      *   quality: 0.75,
-     *   width: 1920, // Height calculated automatically
+     *   width: 1920,
      *   mimeType: 'image/jpeg'
      * });
      * ```
@@ -104,8 +115,10 @@ export interface CompressImageOptions {
      * - iOS: `file://` URLs or absolute paths
      * - Android: `content://` URIs, `file://` URLs, or absolute paths
      *
+     * Common input formats include JPEG, PNG, WebP, GIF, BMP, TIFF, and HEIF/HEIC.
+     *
      * @since 7.0.0
-     * @example "file:///var/mobile/Containers/Data/Application/image.jpg" // iOS
+     * @example "file:///var/mobile/Containers/Data/Application/photo.heic" // iOS HEIF
      * @example "content://com.android.providers.downloads.documents/document/msf%3A1000000485" // Android
      * @example "/storage/emulated/0/Download/photo.png" // Android absolute path
      */
@@ -145,6 +158,7 @@ export interface CompressImageOptions {
      *
      * Higher quality values result in larger files but better visual quality.
      * The actual compression ratio depends on the image content and format.
+     * PNG output ignores quality because it is lossless.
      *
      * @since 7.0.0
      * @default 0.6
@@ -161,8 +175,8 @@ export interface CompressImageOptions {
      * If only width is specified, height is calculated automatically
      * to maintain the original aspect ratio.
      *
-     * If both width and height are specified, the image is resized
-     * to exact dimensions (may distort if ratio differs).
+     * If both width and height are specified, the image is scaled to fit inside
+     * that box while preserving aspect ratio. Images are never upscaled.
      *
      * @since 7.0.0
      * @example 1920 // Full HD width
@@ -178,8 +192,8 @@ export interface CompressImageOptions {
      * If only height is specified, width is calculated automatically
      * to maintain the original aspect ratio.
      *
-     * If both width and height are specified, the image is resized
-     * to exact dimensions (may distort if ratio differs).
+     * If both width and height are specified, the image is scaled to fit inside
+     * that box while preserving aspect ratio. Images are never upscaled.
      *
      * @since 7.0.0
      * @example 1080 // Full HD height
@@ -191,18 +205,24 @@ export interface CompressImageOptions {
      * The MIME type of the compressed output image.
      *
      * **Platform Support:**
-     * - **iOS:** `image/jpeg` only
-     * - **Android:** `image/jpeg`, `image/webp`
-     * - **Web:** `image/jpeg`, `image/webp`
+     * - **iOS:** `image/jpeg`, `image/png`, `image/heif`, `image/heic`, `image/webp` (iOS 14+)
+     * - **Android:** `image/jpeg`, `image/png`, `image/webp`
+     * - **Web:** `image/jpeg`, `image/png`, `image/webp`
+     *
+     * Use this option to convert the source image to another format while compressing.
      *
      * **Format Characteristics:**
      * - **JPEG:** Universal support, good for photos, no transparency
-     * - **WebP:** Better compression, supports transparency, not on iOS
+     * - **PNG:** Lossless, supports transparency
+     * - **WebP:** Better compression, supports transparency
+     * - **HEIF/HEIC:** Efficient photo format on iOS
      *
      * @since 7.0.0
      * @default "image/jpeg"
-     * @example "image/jpeg" // JPEG format (all platforms)
-     * @example "image/webp" // WebP format (Android/Web only)
+     * @example "image/jpeg" // JPEG format
+     * @example "image/png" // PNG format
+     * @example "image/webp" // WebP format
+     * @example "image/heif" // HEIF format (iOS output)
      */
     mimeType?: string;
 }
@@ -229,7 +249,7 @@ export interface CompressImageResult {
      *
      * @since 7.0.0
      * @example "/var/mobile/Containers/Data/tmp/compressed_abc123.jpg" // iOS
-     * @example "/data/user/0/com.app/cache/compressed_xyz789.jpg" // Android
+     * @example "/data/user/0/com.app/cache/compressed_xyz789.webp" // Android
      */
     path?: string;
     /**