@turbodocx/html-to-docx 1.15.3 → 1.17.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>";
@@ -203,11 +220,33 @@ full fledged examples can be found under `example/`
     - `restart` <"continuous"|"newPage"|"newSection"> numbering restart strategy. Defaults to `continuous`.
   - `numbering` <?[Object]>
     - `defaultOrderedListStyleType` <?[String]> default ordered list style type. Defaults to `decimal`.
+  - `heading` <?[Object]> custom heading styles configuration
+  - `heading1`-`heading6` <?[Object]> heading style configuration
+    - `font` <?[String]> font family
+    - `fontSize` <?[Number]> font size in half-points
+    - `bold` <?[Boolean]> whether text is bold. Defaults to `true`
+    - `spacing` <?[Object]> paragraph spacing configuration
+      - `before` <?[Number]> spacing before heading in twips
+      - `after` <?[Number]> spacing after heading in twips
+    - `keepLines` <?[Boolean]> keep lines together. Defaults to `true`
+    - `keepNext` <?[Boolean]> keep with next paragraph. Defaults to `true`
+    - `outlineLevel` <?[Number]> outline level (0-5)
   - `decodeUnicode` <?[Boolean]> flag to enable unicode decoding of header, body and footer. Defaults to `false`.
   - `lang` <?[String]> language localization code for spell checker to work properly. Defaults to `en-US`.
   - `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`.
 - `footerHTMLString` <[String]> clean html string equivalent of footer. Defaults to `<p></p>` if footer flag is `true`.
 
 ### Returns