node-pptx-templater 1.1.7 → 1.1.10

package/README.md

@@ -13,7 +13,7 @@
   <a href="https://github.com/jsuyog2/node-pptx-templater/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/jsuyog2/node-pptx-templater/ci.yml?branch=main&style=flat-square&color=34d399" alt="CI"></a>
   <a href="https://www.npmjs.com/package/node-pptx-templater"><img src="https://img.shields.io/npm/dm/node-pptx-templater.svg?style=flat-square&color=a855f7" alt="Downloads"></a>
   <a href="./LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square" alt="MIT License"></a>
-  <a href="https://nodejs.org"><img src="https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen?style=flat-square" alt="Node.js 18+"></a>
+  <a href="https://nodejs.org"><img src="https://img.shields.io/badge/node-%3E%3D20.12.0-brightgreen?style=flat-square" alt="Node.js 20.12.0+"></a>
 </p>
 
 <p align="center">

package/package.json

@@ -1,11 +1,16 @@
 {
   "name": "node-pptx-templater",
-  "version": "1.1.7",
+  "version": "1.1.10",
   "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",
+  "module": "./src/index.mjs",
+  "types": "./src/index.d.ts",
   "type": "commonjs",
+  "sideEffects": false,
   "exports": {
     ".": {
+      "types": "./src/index.d.ts",
+      "import": "./src/index.mjs",
       "require": "./src/index.js"
     }
   },
@@ -169,26 +174,39 @@
   },
   "homepage": "https://jsuyog2.github.io/node-pptx-templater",
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=20.12.0"
   },
   "dependencies": {
-    "fast-xml-parser": "^4.3.6",
-    "jszip": "^3.10.1",
-    "fs-extra": "^11.2.0",
-    "commander": "^12.0.0",
     "chalk": "^4.1.2",
+    "commander": "^12.0.0",
+    "fast-xml-parser": "^5.9.3",
+    "fs-extra": "^11.2.0",
+    "jszip": "^3.10.1",
     "ora": "^5.4.1"
   },
   "devDependencies": {
-    "vitest": "^1.6.0",
-    "@vitest/coverage-v8": "^1.6.0",
+    "@vitest/coverage-v8": "^4.1.9",
     "eslint": "^8.57.0",
-    "prettier": "^3.2.5"
+    "prettier": "^3.2.5",
+    "vitest": "^4.1.9"
   },
   "files": [
     "src/",
     "README.md",
     "LICENSE",
     "CHANGELOG.md"
-  ]
-}
+  ],
+  "browser": {
+    "fs": false,
+    "path": false,
+    "os": false,
+    "stream": false,
+    "fs-extra": false,
+    "ora": false,
+    "chalk": false,
+    "commander": false
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/index.d.ts

@@ -0,0 +1,138 @@
+export class PPTXTemplater {
+  static load(source: string | Buffer, options?: any): Promise<PPTXTemplater>;
+  static setLogLevel(level: string): void;
+  static preload(source: string | Buffer): Promise<any>;
+  static cache(source: string | Buffer): Promise<any>;
+  static fromCache(source: string | Buffer): Promise<PPTXTemplater>;
+  static clearCache(): void;
+  static fromPresentationXml(options: any): Promise<PPTXTemplater>;
+  static create(): Promise<PPTXTemplater>;
+  static extractPptx(pptxPath: string, outputPath: string, options?: any): Promise<void>;
+  static buildPptx(folderPath: string, pptxPath: string): Promise<void>;
+
+  slideCount: number;
+  useSlide(slideNumber: number): this;
+  replaceText(replacements: Record<string, string | number>): this;
+  updateChart(chartName: string, data: any): this;
+  updateChartTitle(chartName: string, title: string): this;
+  applyZOrder(slideNumber: number, zOrderConfig: any[]): this;
+  removeSlide(slideNumber: number): this;
+  addHyperlink(options: any): this;
+  addSlideLink(options: any): this;
+  getTableRows(tableName: string): Promise<any[]>;
+  updateTable(tableName: string, rows: any[][]): this;
+  addTableRow(tableName: string, row: any[]): this;
+  removeTableRow(tableName: string, rowIndex: number): this;
+  mergeCells(tableName: string, startRow: number, startCol: number, endRow: number, endCol: number): this;
+  saveToFile(filePath: string, options?: any): Promise<void>;
+  save(filePath: string, options?: any): Promise<void>;
+  saveXml(folderPath: string): Promise<void>;
+  saveToFolder(folderPath: string): Promise<void>;
+  toBuffer(options?: any): Promise<Buffer>;
+  toStream(options?: any): Promise<any>;
+  saveToStream(writableOrOptions: any, options?: any): Promise<void>;
+  exportSlides(...slideNumbers: number[]): Promise<any>;
+  importSlideFrom(sourceEngine: PPTXTemplater, slideRef: any): Promise<any>;
+  repair(): Promise<this>;
+  inspectXML(xmlPath: string): Promise<any>;
+  validateCharts(): Promise<any>;
+  repairCharts(): Promise<any>;
+  inspectChartXML(chartFileName: string): Promise<any>;
+  getDataLabels(chartId: string, options?: any): Promise<any>;
+  validateDataLabels(chartId: string, options?: any): Promise<any>;
+  validateChartLabels(chartId: string, options?: any): Promise<any>;
+  validateSeriesNameLabels(chartId: string, options?: any): Promise<any>;
+  getChartLabelPositions(chartId: string): Promise<any>;
+  getChartBarPositions(chartId: string): Promise<any>;
+  addShape(typeOrOptions: any, options?: any): Promise<any>;
+  updateShape(shapeId: string, options: any): Promise<any>;
+  removeShape(shapeId: string): Promise<any>;
+  addCellShape(tableId: string, rowIndex: number, colIndex: number, options: any): Promise<any>;
+  updateCellShape(tableId: string, rowIndex: number, colIndex: number, shapeIndex: number, options: any): Promise<any>;
+  removeCellShape(tableId: string, rowIndex: number, colIndex: number, shapeIndex: number): Promise<any>;
+  replaceImage(imageIdOrName: string, sourcePathOrBuffer: string | Buffer): Promise<any>;
+  addImage(sourcePathOrBuffer: string | Buffer, options?: any): Promise<any>;
+  validatePresentation(): Promise<any>;
+  validatePresentationXml(): Promise<any>;
+  validateSlide(slideIndex: number): Promise<any>;
+  validateTable(tableId: string): Promise<any>;
+  validateArchive(): Promise<any>;
+}
+
+export const PPTXTemplate: typeof PPTXTemplater;
+
+export class ZipManager {
+  [key: string]: any;
+}
+
+export class XMLParser {
+  [key: string]: any;
+}
+
+export const Z_ORDER_SYMBOL: unique symbol;
+
+export class SlideManager {
+  [key: string]: any;
+}
+
+export class ChartManager {
+  [key: string]: any;
+}
+
+export class TableManager {
+  [key: string]: any;
+}
+
+export class ShapeManager {
+  [key: string]: any;
+}
+
+export class ImageManager {
+  [key: string]: any;
+}
+
+export class TextManager {
+  [key: string]: any;
+}
+
+export class HyperlinkManager {
+  [key: string]: any;
+}
+
+export class MediaManager {
+  [key: string]: any;
+}
+
+export class RelationshipManager {
+  [key: string]: any;
+}
+
+export class OutputWriter {
+  [key: string]: any;
+}
+
+export class TemplateEngine {
+  [key: string]: any;
+}
+
+export class ValidationEngine {
+  [key: string]: any;
+}
+
+export function generateRelationshipId(slideId: any): string;
+export function parseRelationshipId(relId: string): any;
+export function validateXml(xmlStr: string): any;
+export function validateXML(xmlStr: string): any;
+export function safeParseXml(xmlStr: string): any;
+export function repairXML(xmlStr: string): string;
+export function scanForEntities(xmlStr: string): any;
+export function analyzeXmlFile(xmlStr: string): any;
+export function reportXmlComplexity(xmlStr: string): any;
+export function createLogger(name: string): any;
+export function setGlobalLogLevel(level: string): void;
+export function resetLogLevel(): void;
+
+export class PPTXError extends Error {}
+export class SlideNotFoundError extends PPTXError {}
+export class ChartNotFoundError extends PPTXError {}
+export class TableNotFoundError extends PPTXError {}

package/src/index.mjs

@@ -0,0 +1,39 @@
+import pkg from './index.js'
+
+export const {
+  PPTXTemplater,
+  PPTXTemplate,
+  ZipManager,
+  XMLParser,
+  Z_ORDER_SYMBOL,
+  SlideManager,
+  ChartManager,
+  TableManager,
+  ShapeManager,
+  ImageManager,
+  TextManager,
+  HyperlinkManager,
+  MediaManager,
+  RelationshipManager,
+  OutputWriter,
+  TemplateEngine,
+  ValidationEngine,
+  generateRelationshipId,
+  parseRelationshipId,
+  validateXml,
+  validateXML,
+  safeParseXml,
+  repairXML,
+  scanForEntities,
+  analyzeXmlFile,
+  reportXmlComplexity,
+  createLogger,
+  setGlobalLogLevel,
+  resetLogLevel,
+  PPTXError,
+  SlideNotFoundError,
+  ChartNotFoundError,
+  TableNotFoundError,
+} = pkg
+
+export default pkg

package/src/managers/RelationshipManager.js

@@ -114,7 +114,8 @@ class RelationshipManager {
       relFiles.map(async relsPath => {
         const content = await zipManager.readFile(relsPath)
         if (content) {
-          this.#relationships.set(relsPath, this.#parseRels(content, relsPath))
+          const normalizedPath = this.#normalizeRelsPath(relsPath)
+          this.#relationships.set(normalizedPath, this.#parseRels(content, relsPath))
         }
       })
     )
@@ -122,6 +123,31 @@ class RelationshipManager {
     logger.debug(`Loaded ${this.#relationships.size} relationship files`)
   }
 
+  /**
+   * Normalizes path separators and strips leading slashes for robust lookup.
+   * @private
+   * @param {string} path
+   * @returns {string}
+   */
+  #normalizeRelsPath(path) {
+    if (!path) return ''
+    let normalized = path.replace(/\\/g, '/')
+    if (normalized.startsWith('/')) {
+      normalized = normalized.substring(1)
+    }
+    return normalized
+  }
+
+  /**
+   * Gets the normalized key for a part's relationships map.
+   * @private
+   * @param {string} partPath
+   * @returns {string}
+   */
+  #getNormalizedKey(partPath) {
+    return this.#normalizeRelsPath(this.getRelsPath(partPath))
+  }
+
   /**
    * Returns the relationship file path for a given part path.
    *
@@ -133,9 +159,10 @@ class RelationshipManager {
    * @returns {string} Path to the corresponding .rels file.
    */
   getRelsPath(partPath) {
-    const lastSlash = partPath.lastIndexOf('/')
-    const dir = lastSlash >= 0 ? partPath.substring(0, lastSlash) : ''
-    const file = lastSlash >= 0 ? partPath.substring(lastSlash + 1) : partPath
+    const normalizedPartPath = partPath.replace(/\\/g, '/')
+    const lastSlash = normalizedPartPath.lastIndexOf('/')
+    const dir = lastSlash >= 0 ? normalizedPartPath.substring(0, lastSlash) : ''
+    const file = lastSlash >= 0 ? normalizedPartPath.substring(lastSlash + 1) : normalizedPartPath
     return dir ? `${dir}/_rels/${file}.rels` : `_rels/${file}.rels`
   }
 
@@ -146,8 +173,8 @@ class RelationshipManager {
    * @returns {Relationship[]} Array of relationships.
    */
   getRelationships(partPath) {
-    const relsPath = this.getRelsPath(partPath)
-    return this.#relationships.get(relsPath) || []
+    const key = this.#getNormalizedKey(partPath)
+    return this.#relationships.get(key) || []
   }
 
   /**
@@ -184,20 +211,20 @@ class RelationshipManager {
    * @returns {string} The assigned relationship ID (e.g., 'rId3').
    */
   addRelationship(partPath, type, target, targetMode) {
-    const relsPath = this.getRelsPath(partPath)
+    const key = this.#getNormalizedKey(partPath)
 
-    if (!this.#relationships.has(relsPath)) {
-      this.#relationships.set(relsPath, [])
+    if (!this.#relationships.has(key)) {
+      this.#relationships.set(key, [])
     }
 
-    const existing = this.#relationships.get(relsPath)
+    const existing = this.#relationships.get(key)
     const newId = generateRelationshipId(existing.map(r => r.id))
 
     const rel = { id: newId, type, target }
     if (targetMode) rel.targetMode = targetMode
 
     existing.push(rel)
-    this.#flushRels(relsPath, partPath)
+    this.#flushRels(key, partPath)
 
     logger.debug(`Added relationship ${newId} (${type.split('/').pop()}) to ${partPath}`)
     return newId
@@ -210,11 +237,11 @@ class RelationshipManager {
    * @param {string} rId - Relationship ID to remove.
    */
   removeRelationship(partPath, rId) {
-    const relsPath = this.getRelsPath(partPath)
-    const existing = this.#relationships.get(relsPath) || []
+    const key = this.#getNormalizedKey(partPath)
+    const existing = this.#relationships.get(key) || []
     const filtered = existing.filter(r => r.id !== rId)
-    this.#relationships.set(relsPath, filtered)
-    this.#flushRels(relsPath, partPath)
+    this.#relationships.set(key, filtered)
+    this.#flushRels(key, partPath)
   }
 
   /**
@@ -225,12 +252,12 @@ class RelationshipManager {
    * @param {string} newTarget - New target value.
    */
   updateRelationshipTarget(partPath, rId, newTarget) {
-    const relsPath = this.getRelsPath(partPath)
-    const existing = this.#relationships.get(relsPath) || []
+    const key = this.#getNormalizedKey(partPath)
+    const existing = this.#relationships.get(key) || []
     const rel = existing.find(r => r.id === rId)
     if (rel) {
       rel.target = newTarget
-      this.#flushRels(relsPath, partPath)
+      this.#flushRels(key, partPath)
     }
   }
 
@@ -245,14 +272,14 @@ class RelationshipManager {
    */
   copyRelationships(sourcePath, destPath, excludeTypes = []) {
     const sourceRels = this.getRelationships(sourcePath)
-    const destRelsPath = this.getRelsPath(destPath)
+    const destKey = this.#getNormalizedKey(destPath)
     const idMap = new Map()
 
-    if (!this.#relationships.has(destRelsPath)) {
-      this.#relationships.set(destRelsPath, [])
+    if (!this.#relationships.has(destKey)) {
+      this.#relationships.set(destKey, [])
     }
 
-    const destRels = this.#relationships.get(destRelsPath)
+    const destRels = this.#relationships.get(destKey)
 
     for (const rel of sourceRels) {
       if (excludeTypes.includes(rel.type)) continue
@@ -262,7 +289,7 @@ class RelationshipManager {
       idMap.set(rel.id, newId)
     }
 
-    this.#flushRels(destRelsPath, destPath)
+    this.#flushRels(destKey, destPath)
     return idMap
   }
 
@@ -329,10 +356,11 @@ class RelationshipManager {
    * @param {string} partPath - For logging.
    */
   #flushRels(relsPath, _partPath) {
-    const rels = this.#relationships.get(relsPath) || []
+    const key = this.#normalizeRelsPath(relsPath)
+    const rels = this.#relationships.get(key) || []
     const xml = this.#buildRelsXml(rels)
     if (this.#zipManager) {
-      this.#zipManager.writeFile(relsPath, xml)
+      this.#zipManager.writeFile(key, xml)
     }
   }
 

package/src/managers/SlideManager.js

@@ -433,6 +433,7 @@ class SlideManager {
   cloneSlide(sourceIndex, atPosition, relationshipManager) {
     this.#assertSlideExists(sourceIndex)
     const sourceInfo = this.#slides.get(sourceIndex)
+    console.log('[DEBUG] Source Slide Info:', sourceInfo)
 
     const newIndex = this.#slides.size + 1
     let nextFileIndex = 1
@@ -444,11 +445,21 @@ class SlideManager {
 
     // Copy the source XML
     let sourceXml = this.getSlideXml(sourceIndex)
+    console.log('[DEBUG] Source XML length:', sourceXml ? sourceXml.length : 0)
+
+    // Copy relationships
+    const sourceRels = relationshipManager.getRelationships(sourceInfo.zipPath)
+    console.log(
+      '[DEBUG] Source Rels Path searched:',
+      relationshipManager.getRelsPath(sourceInfo.zipPath)
+    )
+    console.log('[DEBUG] Source Rels found:', sourceRels)
 
     // Copy relationships from source slide (excluding notes, which are slide-specific)
     const idMap = relationshipManager.copyRelationships(sourceInfo.zipPath, slideZipPath, [
       REL_TYPES.NOTES_SLIDE,
     ])
+    console.log('[DEBUG] Copied relationship ID map:', Array.from(idMap.entries()))
 
     // Remap relationship IDs in the cloned XML to match the new targets
     sourceXml = remapRelationshipIds(sourceXml, idMap)

package/src/managers/ZipManager.js

@@ -213,6 +213,19 @@ class ZipManager {
     logger.debug('Created blank PPTX structure')
   }
 
+  /**
+   * Normalizes path separators and strips leading slashes.
+   * @private
+   */
+  #normalizePath(zipPath) {
+    if (!zipPath) return ''
+    let normal = zipPath.replace(/\\/g, '/')
+    if (normal.startsWith('/')) {
+      normal = normal.substring(1)
+    }
+    return normal
+  }
+
   /**
    * Reads and caches a text file from the ZIP archive.
    *
@@ -221,7 +234,7 @@ class ZipManager {
    */
   async readFile(zipPath) {
     // Normalize path separators
-    const normalPath = zipPath.replace(/\\/g, '/')
+    const normalPath = this.#normalizePath(zipPath)
 
     // Return cached version if available and not dirty
     if (this.#xmlCache.has(normalPath) && !this.#dirtyFiles.has(normalPath)) {
@@ -239,8 +252,11 @@ class ZipManager {
       if (entry.type === 'text') {
         content = entry.content
       } else {
-        const { TextDecoder } = require('util')
-        content = new TextDecoder('utf-8').decode(entry.content)
+        const decoder =
+          typeof globalThis.TextDecoder !== 'undefined'
+            ? new globalThis.TextDecoder('utf-8')
+            : new (require('util').TextDecoder)('utf-8')
+        content = decoder.decode(entry.content)
       }
       this.#xmlCache.set(normalPath, content)
       return content
@@ -278,7 +294,7 @@ class ZipManager {
    * @returns {string|null} Cached content or null.
    */
   readCachedFile(zipPath) {
-    const normalPath = zipPath.replace(/\\/g, '/')
+    const normalPath = this.#normalizePath(zipPath)
     if (this.#dirtyFiles.has(normalPath)) {
       return this.#dirtyFiles.get(normalPath)
     }
@@ -291,8 +307,11 @@ class ZipManager {
       if (entry.type === 'text') {
         content = entry.content
       } else {
-        const { TextDecoder } = require('util')
-        content = new TextDecoder('utf-8').decode(entry.content)
+        const decoder =
+          typeof globalThis.TextDecoder !== 'undefined'
+            ? new globalThis.TextDecoder('utf-8')
+            : new (require('util').TextDecoder)('utf-8')
+        content = decoder.decode(entry.content)
       }
       this.#xmlCache.set(normalPath, content)
       return content
@@ -307,7 +326,7 @@ class ZipManager {
    * @returns {Promise<Uint8Array|null>} Binary content or null if not found.
    */
   async readBinaryFile(zipPath) {
-    const normalPath = zipPath.replace(/\\/g, '/')
+    const normalPath = this.#normalizePath(zipPath)
     if (this.#dirtyBinaryFiles.has(normalPath)) {
       return this.#dirtyBinaryFiles.get(normalPath)
     }
@@ -329,7 +348,7 @@ class ZipManager {
   }
 
   writeFile(zipPath, content) {
-    const normalPath = zipPath.replace(/\\/g, '/')
+    const normalPath = this.#normalizePath(zipPath)
     this.#dirtyFiles.set(normalPath, content)
     this.#xmlCache.set(normalPath, content)
     this.#removedFiles.delete(normalPath)
@@ -340,7 +359,7 @@ class ZipManager {
   }
 
   writeBinaryFile(zipPath, data) {
-    const normalPath = zipPath.replace(/\\/g, '/')
+    const normalPath = this.#normalizePath(zipPath)
     this.#dirtyBinaryFiles.set(normalPath, data)
     this.#removedFiles.delete(normalPath)
     if (this.#zip) {
@@ -380,7 +399,7 @@ class ZipManager {
    * @param {string} zipPath - Path to remove.
    */
   removeFile(zipPath) {
-    const normalPath = zipPath.replace(/\\/g, '/')
+    const normalPath = this.#normalizePath(zipPath)
     this.#removedFiles.add(normalPath)
     this.#xmlCache.delete(normalPath)
     this.#dirtyFiles.delete(normalPath)
@@ -397,7 +416,7 @@ class ZipManager {
    * @returns {boolean}
    */
   hasFile(zipPath) {
-    const normalPath = zipPath.replace(/\\/g, '/')
+    const normalPath = this.#normalizePath(zipPath)
     if (this.#removedFiles.has(normalPath)) return false
     if (this.#dirtyFiles.has(normalPath) || this.#dirtyBinaryFiles.has(normalPath)) return true
     if (this.#cachedFiles && this.#cachedFiles.has(normalPath)) return true