@turbodocx/html-to-docx 1.16.0 → 1.18.0

package/README.md

@@ -3,6 +3,7 @@
 @turbodocx/html-to-docx
 ====================
 [![NPM Version][npm-image]][npm-url]
+[![CodeQL](https://github.com/TurboDocx/html-to-docx/workflows/CodeQL/badge.svg)](https://github.com/TurboDocx/html-to-docx/actions/workflows/codeql.yml)
 [![GitHub Stars](https://img.shields.io/github/stars/turbodocx/html-to-docx?style=social)](https://github.com/turbodocx/html-to-docx)
 [![Type Script](https://shields.io/badge/TypeScript-3178C6?logo=TypeScript&logoColor=FFF&style=flat-square)](https://typescript.org)
 [![Discord](https://img.shields.io/badge/Discord-Join%20Us-7289DA?logo=discord)](https://discord.gg/NYKwz4BcpX)
@@ -88,6 +89,22 @@ async function withOptions() {
   });
 }
 
+// With image processing options
+async function withImageOptions() {
+  const htmlWithImages = `<div>
+    <img src="https://example.com/image.jpg" alt="Example">
+  </div>`;
+  
+  const docx = await HtmlToDocx(htmlWithImages, null, {
+    imageProcessing: {
+      maxRetries: 3,          // Retry failed image downloads up to 3 times
+      verboseLogging: true,   // Enable detailed logging for debugging
+      downloadTimeout: 10000, // 10 second timeout per download attempt
+      maxImageSize: 5242880   // 5MB max image size
+    }
+  });
+}
+
 // With all parameters
 async function complete() {
   const headerHtml = "<p>Document Header</p>";
@@ -219,6 +236,20 @@ full fledged examples can be found under `example/`
   - `direction` <?[String]> text direction for RTL (right-to-left) languages. Set to `'rtl'` for Arabic, Hebrew, etc. Defaults to `'ltr'`.
   - `preProcessing` <?[Object]>
     - `skipHTMLMinify` <?[Boolean]> flag to skip minification of HTML. Defaults to `false`.
+  - `imageProcessing` <?[Object]>
+    - `maxRetries` <?[Number]> maximum number of retry attempts for failed image downloads. Defaults to `2`.
+    - `verboseLogging` <?[Boolean]> flag to enable detailed logging of image processing operations. Defaults to `false`.
+    - `downloadTimeout` <?[Number]> timeout in milliseconds for each image download attempt. Defaults to `5000` (5 seconds).
+    - `maxImageSize` <?[Number]> maximum allowed image size in bytes. Defaults to `10485760` (10MB).
+    - `retryDelayBase` <?[Number]> base delay in milliseconds for exponential backoff between retries. Defaults to `500` (500ms).
+    - `minTimeout` <?[Number]> minimum timeout in milliseconds. Defaults to `1000` (1 second).
+    - `maxTimeout` <?[Number]> maximum timeout in milliseconds. Defaults to `30000` (30 seconds).
+    - `minImageSize` <?[Number]> minimum image size in bytes. Defaults to `1024` (1KB).
+    - `maxCacheSize` <?[Number]> maximum total cache size in bytes (LRU cache limit to prevent OOM). Defaults to `20971520` (20MB).
+    - `maxCacheEntries` <?[Number]> maximum number of unique images in cache (LRU eviction). Defaults to `100`.
+    - `svgHandling` <?[String]> strategy for handling SVG images. Defaults to `'convert'`. Options:
+      - `'convert'` - Converts SVG to PNG for maximum compatibility with all Word versions (requires `sharp` package)
+      - `'native'` - Embeds SVG natively for Office 2019+ (preserves vector quality)
 - `footerHTMLString` <[String]> clean html string equivalent of footer. Defaults to `<p></p>` if footer flag is `true`.
 
 ### Returns
@@ -252,6 +283,130 @@ Also you could add attribute `data-start="n"` to start the numbering from the n-
 `<ol data-start="2">` will start the numbering from ( B. b. II. ii. 2. )
 
 
+## SVG Image Support
+
+The library provides comprehensive SVG image support with two strategies to fit your needs:
+
+### Installation & Package Size
+
+The library supports SVG images with [`sharp`](https://sharp.pixelplumbing.com/) as an optional peer dependency for high-quality SVG→PNG conversion.
+
+**Basic Installation** (Lightweight):
+```bash
+npm install @turbodocx/html-to-docx
+```
+- **Package size**: ~2.8MB (sharp not included)
+- **Compatibility**: SVGs embedded natively - requires Office 2019+ or Microsoft 365
+- **Best for**: Modern-only environments or size-constrained deployments (Lambda, Edge)
+- **Auto-fallback**: Library automatically uses native SVG mode when sharp is unavailable
+
+**Full Installation** (Maximum Compatibility - Recommended):
+```bash
+npm install @turbodocx/html-to-docx sharp
+```
+- **Base package**: ~2.8MB
+- **With sharp**: Additional ~34MB (platform-specific native binaries)
+- **Compatibility**: Converts SVGs to PNG - works with all Word versions (2007+)
+- **Best for**: Production applications requiring broad compatibility
+
+#### Why is sharp optional?
+
+Sharp is a native Node.js module that provides the best SVG to PNG conversion quality, but adds ~34MB of platform-specific native binaries to your `node_modules`. We've made it an optional peer dependency so you can choose:
+
+| Configuration | Install Command | Size | SVG Handling | Word Compatibility | Use Case |
+|--------------|-----------------|------|--------------|-------------------|----------|
+| **Without sharp** (default) | `npm install @turbodocx/html-to-docx` | 2.8MB | Native SVG | Office 2019+ only | Modern environments, Lambda/edge functions |
+| **With sharp** (recommended) | `npm install @turbodocx/html-to-docx sharp` | 2.8MB + 34MB binaries | PNG conversion | All versions (2007+) | Production apps, broad compatibility |
+
+The library **gracefully handles both scenarios** - if sharp is unavailable, SVGs are automatically embedded in native format.
+
+### 1. Convert to PNG (Default - Maximum Compatibility)
+
+By default, SVG images are automatically converted to PNG format for maximum compatibility with all Word versions (requires `sharp`):
+
+```javascript
+const htmlWithSVG = `
+  <div>
+    <img src="data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIxMDAiIGhlaWdodD0iMTAwIj48Y2lyY2xlIGN4PSI1MCIgY3k9IjUwIiByPSI0MCIgZmlsbD0iIzM0OThkYiIvPjwvc3ZnPg==" alt="Circle">
+  </div>
+`;
+
+// Default behavior - SVG converted to PNG
+const docx = await HTMLtoDOCX(htmlWithSVG);
+
+// Or explicitly set to convert
+const docx = await HTMLtoDOCX(htmlWithSVG, null, {
+  imageProcessing: {
+    svgHandling: 'convert'  // Converts SVG to PNG (default)
+  }
+});
+```
+
+**Benefits:**
+- ✅ Works with all Word versions (2007+)
+- ✅ Compatible with Word Online, Google Docs, LibreOffice
+- ✅ No compatibility warnings or errors
+
+### 2. Native SVG (Office 2019+ Only)
+
+For modern Office environments, you can embed SVG images natively to preserve vector quality:
+
+```javascript
+const htmlWithSVG = `
+  <div>
+    <img src="data:image/svg+xml;base64,..." alt="Vector Graphic">
+  </div>
+`;
+
+const docx = await HTMLtoDOCX(htmlWithSVG, null, {
+  imageProcessing: {
+    svgHandling: 'native'  // Embed SVG natively (Office 2019+)
+  }
+});
+```
+
+**Benefits:**
+- ✅ Perfect vector quality at any zoom level
+- ✅ Smaller file sizes for complex graphics
+- ✅ Editable in modern Office applications
+
+**Requirements:**
+- Microsoft Office 2019 or later
+- Microsoft 365
+- Word for Mac 2019+
+
+**Note:** Older Word versions will show an "unreadable content" error with native SVG. Use `'convert'` mode for backwards compatibility.
+
+### Handling SVG Without Sharp
+
+If `sharp` is not installed (e.g., using `--no-optional`), the library automatically falls back to native SVG embedding:
+
+```javascript
+// Even with svgHandling: 'convert', if sharp unavailable → uses native SVG
+const docx = await HTMLtoDOCX(htmlWithSVG, null, {
+  imageProcessing: {
+    svgHandling: 'convert',         // Tries to convert, falls back to native
+    suppressSharpWarning: false,    // Set to true to suppress warning when sharp is missing
+    verboseLogging: true            // Shows: "Sharp not available, using native SVG"
+  }
+});
+```
+
+**No crashes, no errors** - the library detects sharp availability at runtime and adjusts automatically:
+
+```bash
+# With sharp installed
+✅ SVG → PNG conversion → Works in Word 2007+
+
+# Without sharp (--no-optional)
+ℹ️  SVG → Native embedding → Works in Office 2019+ only
+
+# Suppress the warning (if intentionally using native SVG mode)
+imageProcessing: { suppressSharpWarning: true }
+```
+
+**Pro tip**: For serverless/Lambda deployments with size constraints, install without sharp and set `suppressSharpWarning: true` to avoid console warnings. Document that generated files require Office 2019+.
+
 ## RTL (Right-to-Left) Language Support
 
 The library also supports RTL languages like Arabic and Hebrew. Use the `direction` option to enable RTL text flow: