node-pptx-templater 1.0.17 → 1.0.18

package/README.md

@@ -1340,22 +1340,38 @@ Saves the modified presentation XML structures directly to a folder.
 await ppt.saveToFolder('./output-template');
 ```
 
-#### `toBuffer()`
+#### `toBuffer(options = {})`
 Returns the PPTX content as a Node.js Buffer.
 
+* **Arguments**:
+  * `[options]` (`Object`): Save options.
 * **Returns**: `Promise<Buffer>` - 
 
 ```javascript
-ppt.useSlide(1).toBuffer();
+ppt.useSlide(1).toBuffer(options = {});
 ```
 
-#### `toStream()`
+#### `toStream(options = {})`
 Returns the PPTX content as a readable Node.js Stream.
 
+* **Arguments**:
+  * `[options]` (`Object`): Save options.
 * **Returns**: `Promise<NodeJS.ReadableStream>` - 
 
 ```javascript
-ppt.useSlide(1).toStream();
+ppt.useSlide(1).toStream(options = {});
+```
+
+#### `saveToStream(writableOrOptions, options = {})`
+Saves the presentation to a readable stream or pipes it to a writable stream.
+
+* **Arguments**:
+  * `[writableOrOptions]` (`NodeJS.WritableStream|Object`): Writable stream to pipe to, or options object.
+  * `[options]` (`Object`): Save options if writable stream was passed first.
+* **Returns**: `Promise<NodeJS.ReadableStream|void>` - 
+
+```javascript
+ppt.useSlide(1).saveToStream(writableOrOptions, options = {});
 ```
 
 #### `validatePresentationXml()`
@@ -1387,6 +1403,60 @@ OpenXML relationship IDs follow the format rId1, rId2, rId3, ... They must be un
 ppt.useSlide(1).function();
 ```
 
+#### `preload(())`
+Delegates core actions to slide element sub-managers.
+
+* **Returns**: `PPTXTemplater` - The fluent engine instance.
+
+```javascript
+ppt.useSlide(1).preload(());
+```
+
+#### `cache(())`
+Delegates core actions to slide element sub-managers.
+
+* **Returns**: `PPTXTemplater` - The fluent engine instance.
+
+```javascript
+ppt.useSlide(1).cache(());
+```
+
+#### `fromCache(())`
+Delegates core actions to slide element sub-managers.
+
+* **Returns**: `PPTXTemplater` - The fluent engine instance.
+
+```javascript
+ppt.useSlide(1).fromCache(());
+```
+
+#### `clearCache(())`
+Delegates core actions to slide element sub-managers.
+
+* **Returns**: `PPTXTemplater` - The fluent engine instance.
+
+```javascript
+ppt.useSlide(1).clearCache(());
+```
+
+#### `enablePerformanceProfile(())`
+Delegates core actions to slide element sub-managers.
+
+* **Returns**: `PPTXTemplater` - The fluent engine instance.
+
+```javascript
+ppt.useSlide(1).enablePerformanceProfile(());
+```
+
+#### `getPerformanceMetrics(())`
+Delegates core actions to slide element sub-managers.
+
+* **Returns**: `PPTXTemplater` - The fluent engine instance.
+
+```javascript
+ppt.useSlide(1).getPerformanceMetrics(());
+```
+
 #### `fromPresentationXml(())`
 Delegates core actions to slide element sub-managers.
 
@@ -1881,6 +1951,110 @@ Below are benchmark results compiled on a standard Intel Core i7 system processi
 
 ---
 
+## ⚡ Performance Optimization & Caching APIs
+
+The library provides first-class support for memory optimization, template caching, lazy loading, and streaming saves.
+
+### 1. In-Memory Template Caching (IIS & Server Environments)
+Instead of loading and parsing the PPTX ZIP structure from disk on every request, preload the template once. Subsequent templates can be instantiated from the cache in **0ms**:
+
+```javascript
+const { PPTXTemplater } = require('node-pptx-templater');
+
+// Preload templates into memory cache at server startup
+await PPTXTemplater.preload('./templates/report.pptx');
+
+// Load from cache instantly inside request handlers
+app.post('/generate-report', async (req, res) => {
+  const ppt = await PPTXTemplater.fromCache('./templates/report.pptx');
+  
+  ppt.useSlide(1).replaceText({ '{{title}}': req.body.title });
+  
+  const buffer = await ppt.toBuffer();
+  res.send(buffer);
+});
+
+// Clear cache if templates change
+PPTXTemplater.clearCache();
+```
+
+### 2. Performance Profiling
+Expose timing and memory metrics across the generation pipeline:
+
+```javascript
+const ppt = await PPTXTemplater.load('report.pptx');
+ppt.enablePerformanceProfile();
+
+// Perform modifications...
+ppt.useSlide(1).replaceText({ '{{title}}': 'Performance' });
+
+await ppt.toBuffer();
+
+// Retrieve timing statistics (in milliseconds)
+const metrics = ppt.getPerformanceMetrics();
+console.log(metrics);
+/*
+Output:
+{
+  enabled: true,
+  templateLoadMs: 12.5,
+  parseMs: 45.2,
+  chartUpdateMs: 0,
+  imageUpdateMs: 0,
+  zipGenerationMs: 65.8,
+  totalMs: 125.4,
+  memoryUsedMB: 38.45
+}
+*/
+```
+
+### 3. Configurable ZIP Compression
+Balance CPU execution time and file size when saving the presentation. Compression options support `'none' | 'fast' | 'balanced' | 'maximum'`:
+
+```javascript
+// balanced is the default (level 6 DEFLATE)
+await ppt.save('output.pptx', { compression: 'balanced' });
+
+// maximum compression (level 9 DEFLATE) - best file size, slightly slower
+await ppt.save('output.pptx', { compression: 'maximum' });
+
+// fast compression (level 1 DEFLATE) - fast packaging, good compression
+await ppt.save('output.pptx', { compression: 'fast' });
+
+// none / store (0% compression) - extremely fast, skips compression entirely
+const fastBuffer = await ppt.toBuffer({ compression: 'none' });
+```
+
+### 4. Streaming Save & Streaming Image Input
+Avoid buffering large output files in memory by saving directly to readable/writable streams. You can also pass Readable streams (like `fs.createReadStream`) directly to image APIs:
+
+```javascript
+const fs = require('fs');
+
+const ppt = await PPTXTemplater.load('report.pptx');
+
+// Stream image from file path without loading into memory buffer
+const imageStream = fs.createReadStream('large-image.png');
+await ppt.useSlide(1).replaceImage('placeholder-img', imageStream);
+
+// Stream final PPTX directly to file disk or HTTP response
+const writeStream = fs.createWriteStream('output.pptx');
+await ppt.saveToStream(writeStream);
+```
+
+---
+
+## 🌐 IIS & Windows Server Deployment Guide
+
+When deploying the library on **Windows Server** with **IIS** using `httpPlatformHandler` or `iisnode`, follow these production-ready recommendations:
+
+1. **Preload Large Templates**: Always call `await PPTXTemplater.preload(templatePath)` during application startup. This avoids high IIS request queue concurrency from competing for file handles or causing disk bottlenecks.
+2. **Use Streaming Saves**: For concurrent routes serving large PPTX outputs, use `saveToStream()` to stream data straight into the HTTP response stream rather than buffering the output as large Node buffers.
+3. **Optimize Compression**: If CPU cycles are a bottleneck on the IIS worker process, set `{ compression: 'fast' }` or `{ compression: 'none' }` on your save options.
+4. **Increase httpPlatformHandler Request Limits**: Ensure the `requestTimeout` and `maxConnections` settings in your IIS `web.config` are set appropriately to allow long-running file streaming tasks.
+
+---
+
 ## 🤝 Contributing
 
 We welcome contributions from the community. Please read our [CONTRIBUTING.md](./CONTRIBUTING.md) to set up the development environment, format code, and submit Pull Requests.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "node-pptx-templater",
-  "version": "1.0.17",
+  "version": "1.0.18",
   "description": "High-performance, low-level PowerPoint (PPTX) OpenXML template engine for Node.js. Dynamically replace text, insert images, update charts (with Excel workbook data caching), and merge table cells without PowerPoint corruption or Repair Mode prompts.",
   "main": "./src/index.js",
   "type": "commonjs",

package/src/core/OutputWriter.js

@@ -47,9 +47,9 @@ class OutputWriter {
    * @param {ZipManager} zipManager
    * @returns {Promise<void>}
    */
-  async saveToFile(filePath, slideManager, zipManager) {
+  async saveToFile(filePath, slideManager, zipManager, options = {}) {
     try {
-      const buffer = await this.toBuffer(slideManager, zipManager)
+      const buffer = await this.toBuffer(slideManager, zipManager, options)
       const dir = path.dirname(filePath)
       await ensureDir(dir)
       await writeFile(filePath, buffer)
@@ -60,13 +60,6 @@ class OutputWriter {
     }
   }
 
-  /**
-   * Returns the PPTX as a Node.js Buffer.
-   *
-   * @param {SlideManager} slideManager
-   * @param {ZipManager} zipManager
-   * @returns {Promise<Buffer>}
-   */
   /**
    * Flushes all pending changes from all managers into the ZipManager.
    *
@@ -75,6 +68,9 @@ class OutputWriter {
    * @returns {Promise<void>}
    */
   async flush(slideManager, zipManager) {
+    if (slideManager && typeof slideManager.flush === 'function') {
+      slideManager.flush()
+    }
     await this.#flushAllSlides(slideManager, zipManager)
     this.#contentTypesManager.flush(zipManager)
     await zipManager.waitForPendingWrites()
@@ -85,12 +81,13 @@ class OutputWriter {
    *
    * @param {SlideManager} slideManager
    * @param {ZipManager} zipManager
+   * @param {Object} [options]
    * @returns {Promise<Buffer>}
    */
-  async toBuffer(slideManager, zipManager) {
+  async toBuffer(slideManager, zipManager, options = {}) {
     await this.flush(slideManager, zipManager)
 
-    const buffer = await zipManager.toBuffer()
+    const buffer = await zipManager.toBuffer(options)
     logger.debug(`Generated buffer: ${(buffer.length / 1024).toFixed(1)} KB`)
 
     if (this.debugZip) {
@@ -105,14 +102,15 @@ class OutputWriter {
    *
    * @param {SlideManager} slideManager
    * @param {ZipManager} zipManager
+   * @param {Object} [options]
    * @returns {Promise<Readable>}
    */
-  async toStream(slideManager, zipManager) {
+  async toStream(slideManager, zipManager, options = {}) {
     await this.flush(slideManager, zipManager)
-    const nodeStream = await zipManager.toStream()
+    const nodeStream = await zipManager.toStream(options)
 
     if (this.debugZip) {
-      const buffer = await zipManager.toBuffer()
+      const buffer = await zipManager.toBuffer(options)
       this.printDebugZip(buffer)
     }
 

package/src/core/PPTXTemplater.js

@@ -42,6 +42,7 @@ const { OutputWriter } = require('./OutputWriter.js')
 const { TemplateEngine } = require('./TemplateEngine.js')
 const { createLogger } = require('../utils/logger.js')
 const { PPTXError } = require('../utils/errors.js')
+const { performance } = require('perf_hooks')
 
 const logger = createLogger('PPTXTemplater')
 
@@ -158,6 +159,14 @@ class PPTXTemplater {
    */
   #loaded = false
 
+  /**
+   * @private
+   * @type {Object}
+   */
+  #profiler
+
+  static #templateCache = new Map()
+
   constructor() {
     this.#xmlParser = new XMLParser()
     this.#zipManager = new ZipManager()
@@ -178,6 +187,18 @@ class PPTXTemplater {
     this.#templateEngine = new TemplateEngine(this.#xmlParser)
     this.#zOrderManager = new ZOrderManager(this.#xmlParser)
     this.#outputWriter = new OutputWriter(this.#zipManager, this.#contentTypesManager)
+
+    this.#profiler = {
+      enabled: false,
+      templateLoadMs: 0,
+      parseMs: 0,
+      chartUpdateMs: 0,
+      imageUpdateMs: 0,
+      zipGenerationMs: 0,
+      totalMs: 0,
+      memoryUsedMB: 0,
+      startTime: performance.now(),
+    }
   }
 
   /**
@@ -202,6 +223,95 @@ class PPTXTemplater {
     return engine
   }
 
+  static async preload(source) {
+    let key = source
+    if (Buffer.isBuffer(source)) {
+      const crypto = require('crypto')
+      key = crypto.createHash('sha256').update(source).digest('hex')
+    } else if (typeof source === 'object' && source !== null) {
+      key = JSON.stringify(source)
+    }
+
+    if (PPTXTemplater.#templateCache.has(key)) {
+      return PPTXTemplater.#templateCache.get(key)
+    }
+
+    const zipManager = new ZipManager()
+    await zipManager.load(source)
+    const files = zipManager.listFiles()
+    const cachedFiles = new Map()
+    for (const file of files) {
+      const ext = file.split('.').pop().toLowerCase()
+      const isText = ext === 'xml' || ext === 'rels' || ext === 'txt'
+      if (isText) {
+        const content = await zipManager.readFile(file)
+        cachedFiles.set(file, { type: 'text', content })
+      } else {
+        const content = await zipManager.readBinaryFile(file)
+        cachedFiles.set(file, { type: 'binary', content })
+      }
+    }
+
+    PPTXTemplater.#templateCache.set(key, cachedFiles)
+    return cachedFiles
+  }
+
+  static async cache(source) {
+    return PPTXTemplater.preload(source)
+  }
+
+  static async fromCache(source) {
+    let key = source
+    if (Buffer.isBuffer(source)) {
+      const crypto = require('crypto')
+      key = crypto.createHash('sha256').update(source).digest('hex')
+    } else if (typeof source === 'object' && source !== null) {
+      key = JSON.stringify(source)
+    }
+
+    let cachedFiles = PPTXTemplater.#templateCache.get(key)
+    if (!cachedFiles) {
+      cachedFiles = await PPTXTemplater.preload(source)
+    }
+
+    const engine = new PPTXTemplater()
+    await engine.#initializeFromCache(cachedFiles)
+    return engine
+  }
+
+  static clearCache() {
+    PPTXTemplater.#templateCache.clear()
+  }
+
+  enablePerformanceProfile() {
+    this.#profiler.enabled = true
+    this.#profiler.startTime = performance.now()
+    return this
+  }
+
+  getPerformanceMetrics() {
+    if (!this.#profiler.enabled) {
+      return {
+        enabled: false,
+        message: 'Performance profiling not enabled. Call enablePerformanceProfile() first.',
+      }
+    }
+    const endTime = performance.now()
+    this.#profiler.totalMs = endTime - this.#profiler.startTime
+    this.#profiler.memoryUsedMB = Math.round((process.memoryUsage().rss / 1024 / 1024) * 100) / 100
+
+    return {
+      enabled: true,
+      templateLoadMs: Math.round(this.#profiler.templateLoadMs * 100) / 100,
+      parseMs: Math.round(this.#profiler.parseMs * 100) / 100,
+      chartUpdateMs: Math.round(this.#profiler.chartUpdateMs * 100) / 100,
+      imageUpdateMs: Math.round(this.#profiler.imageUpdateMs * 100) / 100,
+      zipGenerationMs: Math.round(this.#profiler.zipGenerationMs * 100) / 100,
+      totalMs: Math.round(this.#profiler.totalMs * 100) / 100,
+      memoryUsedMB: this.#profiler.memoryUsedMB,
+    }
+  }
+
   /**
    * Loads a template from a PowerPoint XML Presentation format.
    *
@@ -236,10 +346,13 @@ class PPTXTemplater {
    * @param {string|Buffer} source
    */
   async #initialize(source) {
+    const t0 = performance.now()
     logger.debug(`Loading PPTX from ${typeof source === 'string' ? source : 'buffer'}`)
 
     // Load and extract the ZIP archive (PPTX is just a ZIP)
     await this.#zipManager.load(source)
+    const t1 = performance.now()
+    this.#profiler.templateLoadMs = t1 - t0
 
     // Initialize content types manager first!
     await this.#contentTypesManager.initialize(this.#zipManager)
@@ -259,10 +372,46 @@ class PPTXTemplater {
     // Deduplicate and index media files
     await this.#mediaManager.initialize(this.#zipManager)
 
+    const t2 = performance.now()
+    this.#profiler.parseMs = t2 - t1
+
     this.#loaded = true
     logger.debug(`Loaded ${this.#slideManager.slideCount} slides successfully`)
   }
 
+  async #initializeFromCache(cachedFiles) {
+    const t0 = performance.now()
+    logger.debug('Initializing PPTX from cached template')
+
+    const clonedCache = new Map(cachedFiles)
+    await this.#zipManager.loadFromCache(clonedCache)
+    const t1 = performance.now()
+    this.#profiler.templateLoadMs = t1 - t0
+
+    // Initialize content types manager first!
+    await this.#contentTypesManager.initialize(this.#zipManager)
+
+    // Parse the core presentation relationships and structure
+    await this.#relationshipManager.initialize(this.#zipManager)
+
+    // Load all slide references from presentation.xml
+    await this.#slideManager.initialize(this.#zipManager)
+
+    // Pre-load all slide XML into cache to allow synchronous operations like replaceText()
+    await this.#slideManager.preloadAll()
+
+    // Initialize chart manager with zip context
+    await this.#chartManager.initialize(this.#zipManager)
+
+    // Deduplicate and index media files
+    await this.#mediaManager.initialize(this.#zipManager)
+
+    const t2 = performance.now()
+    this.#profiler.parseMs = t2 - t1
+
+    this.#loaded = true
+  }
+
   /**
    * Initializes a blank PPTX structure from embedded template XML.
    * @private
@@ -401,6 +550,7 @@ class PPTXTemplater {
    */
   updateChart(chartId, data) {
     this.#assertLoaded()
+    const t0 = performance.now()
     const targetIndices = this.#getTargetSlideIndices()
 
     for (const slideIndex of targetIndices) {
@@ -413,6 +563,7 @@ class PPTXTemplater {
       )
     }
 
+    this.#profiler.chartUpdateMs += performance.now() - t0
     logger.debug(`Updated chart "${chartId}" in ${targetIndices.length} slide(s)`)
     return this
   }
@@ -999,7 +1150,11 @@ class PPTXTemplater {
       }
     }
     await this.validateArchive()
-    await this.#outputWriter.saveToFile(filePath, this.#slideManager, this.#zipManager)
+
+    const t0 = performance.now()
+    await this.#outputWriter.saveToFile(filePath, this.#slideManager, this.#zipManager, options)
+    this.#profiler.zipGenerationMs += performance.now() - t0
+
     logger.info(`Saved PPTX to ${filePath}`)
   }
 
@@ -1040,23 +1195,64 @@ class PPTXTemplater {
   /**
    * Returns the PPTX content as a Node.js Buffer.
    *
+   * @param {Object} [options] - Save options.
    * @returns {Promise<Buffer>}
    */
-  async toBuffer() {
+  async toBuffer(options = {}) {
     this.#assertLoaded()
     await this.validateArchive()
-    return this.#outputWriter.toBuffer(this.#slideManager, this.#zipManager)
+
+    const t0 = performance.now()
+    const buffer = await this.#outputWriter.toBuffer(this.#slideManager, this.#zipManager, options)
+    this.#profiler.zipGenerationMs += performance.now() - t0
+
+    return buffer
   }
 
   /**
    * Returns the PPTX content as a readable Node.js Stream.
    *
+   * @param {Object} [options] - Save options.
    * @returns {Promise<NodeJS.ReadableStream>}
    */
-  async toStream() {
+  async toStream(options = {}) {
     this.#assertLoaded()
     await this.validateArchive()
-    return this.#outputWriter.toStream(this.#slideManager, this.#zipManager)
+
+    const t0 = performance.now()
+    const stream = await this.#outputWriter.toStream(this.#slideManager, this.#zipManager, options)
+    this.#profiler.zipGenerationMs += performance.now() - t0
+
+    return stream
+  }
+
+  /**
+   * Saves the presentation to a readable stream or pipes it to a writable stream.
+   *
+   * @param {NodeJS.WritableStream|Object} [writableOrOptions] - Writable stream to pipe to, or options object.
+   * @param {Object} [options] - Save options if writable stream was passed first.
+   * @returns {Promise<NodeJS.ReadableStream|void>}
+   */
+  async saveToStream(writableOrOptions, options = {}) {
+    this.#assertLoaded()
+    let writable = null
+    let opts = options
+    if (writableOrOptions && typeof writableOrOptions.write === 'function') {
+      writable = writableOrOptions
+    } else if (writableOrOptions) {
+      opts = writableOrOptions
+    }
+
+    const stream = await this.toStream(opts)
+    if (writable) {
+      return new Promise((resolve, reject) => {
+        stream.pipe(writable)
+        writable.on('finish', resolve)
+        writable.on('error', reject)
+        stream.on('error', reject)
+      })
+    }
+    return stream
   }
 
   // === Slide Features ===
@@ -1721,6 +1917,7 @@ class PPTXTemplater {
   // === Image Features ===
   async replaceImage(imageIdOrName, sourcePathOrBuffer) {
     this.#assertLoaded()
+    const t0 = performance.now()
     const targetIndices = this.#getTargetSlideIndices()
     for (const idx of targetIndices) {
       await this.#imageManager.replaceImage(
@@ -1732,11 +1929,13 @@ class PPTXTemplater {
         this.#relationshipManager
       )
     }
+    this.#profiler.imageUpdateMs += performance.now() - t0
     return this
   }
 
   async addImage(sourcePathOrBuffer, options = {}) {
     this.#assertLoaded()
+    const t0 = performance.now()
     const targetIndices = this.#getTargetSlideIndices()
     for (const idx of targetIndices) {
       await this.#imageManager.addImage(
@@ -1748,6 +1947,7 @@ class PPTXTemplater {
         this.#relationshipManager
       )
     }
+    this.#profiler.imageUpdateMs += performance.now() - t0
     return this
   }
 

package/src/managers/ChartManager.js

@@ -112,8 +112,6 @@ class ChartManager {
       // Chart name is inferred from file name
       const chartName = chartPath.split('/').pop().replace('.xml', '')
       this.#chartRegistry.set(chartName, { zipPath: chartPath, slideIndex: null })
-      // Pre-load the chart XML into cache so that we can read it synchronously if needed
-      await zipManager.readFile(chartPath)
     }
 
     logger.debug(`Found ${chartFiles.length} chart file(s)`)
@@ -869,7 +867,6 @@ class ChartManager {
   #findChartCoordinates(slideXml, chartId, relationshipManager, slideZipPath) {
     const gfPattern = /<p:graphicFrame>([\s\S]*?)<\/p:graphicFrame>/g
     let match
-    const escapedChartId = chartId.replace(/[-\/\\^$*+?.()|[\]{}]/g, '\\$&')
     while ((match = gfPattern.exec(slideXml)) !== null) {
       const gfContent = match[0]
       const nameMatch = /<p:cNvPr[^>]*name="([^"]+)"/.exec(gfContent)