node-pptx-templater 1.0.0

package/src/utils/contentTypesHelper.js

@@ -0,0 +1,149 @@
+/**
+ * @fileoverview Content Types helper - manages [Content_Types].xml.
+ *
+ * The [Content_Types].xml file tells the ZIP package parser what
+ * MIME type each file inside is. Every new part (slide, chart, image)
+ * must be registered here.
+ *
+ * Structure:
+ *   <Types xmlns="...">
+ *     <!-- Default: applies to all files with matching extension -->
+ *     <Default Extension="rels" ContentType="application/vnd.openxmlformats-package.relationships+xml"/>
+ *     <Default Extension="xml" ContentType="application/xml"/>
+ *
+ *     <!-- Override: specific part override -->
+ *     <Override PartName="/ppt/slides/slide1.xml"
+ *               ContentType="application/vnd.openxmlformats-officedocument.presentationml.slide+xml"/>
+ *   </Types>
+ */
+
+import { createLogger } from './logger.js';
+
+const logger = createLogger('ContentTypes');
+
+/** MIME type for PPTX slide parts. */
+const SLIDE_CONTENT_TYPE = 'application/vnd.openxmlformats-officedocument.presentationml.slide+xml';
+
+/** MIME type for chart parts. */
+const CHART_CONTENT_TYPE = 'application/vnd.openxmlformats-officedocument.drawingml.chart+xml';
+
+/**
+ * Singleton helper for [Content_Types].xml manipulation.
+ */
+class ContentTypesHelper {
+  /**
+   * Adds a slide Override entry to [Content_Types].xml.
+   *
+   * @param {ZipManager} zipManager
+   * @param {string} slideFileName - e.g., 'slide5.xml'
+   */
+  addSlideContentType(zipManager, slideFileName) {
+    this.#addOverride(
+      zipManager,
+      `/ppt/slides/${slideFileName}`,
+      SLIDE_CONTENT_TYPE
+    );
+  }
+
+  /**
+   * Removes a slide Override entry from [Content_Types].xml.
+   *
+   * @param {ZipManager} zipManager
+   * @param {string} slideFileName - e.g., 'slide5.xml'
+   */
+  removeSlideContentType(zipManager, slideFileName) {
+    this.#removeOverride(
+      zipManager,
+      `/ppt/slides/${slideFileName}`
+    );
+  }
+
+  /**
+   * Adds a chart Override entry to [Content_Types].xml.
+   *
+   * @param {ZipManager} zipManager
+   * @param {string} chartFileName - e.g., 'chart3.xml'
+   */
+  addChartContentType(zipManager, chartFileName) {
+    this.#addOverride(
+      zipManager,
+      `/ppt/charts/${chartFileName}`,
+      CHART_CONTENT_TYPE
+    );
+  }
+
+  /**
+   * Adds a Default entry for a media extension.
+   *
+   * @param {ZipManager} zipManager
+   * @param {string} extension - File extension (e.g., 'png').
+   * @param {string} mimeType - MIME type.
+   */
+  addMediaDefault(zipManager, extension, mimeType) {
+    this.#updateQueue = this.#updateQueue.then(async () => {
+      const xmlFile = zipManager.rawZip.file('[Content_Types].xml');
+      if (!xmlFile) return;
+
+      const content = await xmlFile.async('text');
+      const entry = `Extension="${extension}" ContentType="${mimeType}"`;
+      if (!content.includes(entry)) {
+        const updated = content.replace(
+          '</Types>',
+          `  <Default ${entry}/>\n</Types>`
+        );
+        zipManager.writeFile('[Content_Types].xml', updated);
+        logger.debug(`Registered default content type for .${extension}`);
+      }
+    });
+    zipManager.addPendingPromise(this.#updateQueue);
+  }
+
+  #updateQueue = Promise.resolve();
+
+  /**
+   * Adds an Override entry to [Content_Types].xml.
+   * @private
+   */
+  #addOverride(zipManager, partName, contentType) {
+    this.#updateQueue = this.#updateQueue.then(async () => {
+      const xmlFile = zipManager.rawZip.file('[Content_Types].xml');
+      if (!xmlFile) {
+        logger.warn('[Content_Types].xml not found');
+        return;
+      }
+      const content = await xmlFile.async('text');
+      const entry = `PartName="${partName}"`;
+      if (!content.includes(entry)) {
+        const override = `<Override PartName="${partName}" ContentType="${contentType}"/>`;
+        const updated = content.replace('</Types>', `  ${override}\n</Types>`);
+        zipManager.writeFile('[Content_Types].xml', updated);
+        logger.debug(`Registered content type for ${partName}`);
+      }
+    });
+    zipManager.addPendingPromise(this.#updateQueue);
+  }
+
+  /**
+   * Removes an Override entry from [Content_Types].xml.
+   * @private
+   */
+  #removeOverride(zipManager, partName) {
+    this.#updateQueue = this.#updateQueue.then(async () => {
+      const xmlFile = zipManager.rawZip.file('[Content_Types].xml');
+      if (!xmlFile) {
+        logger.warn('[Content_Types].xml not found');
+        return;
+      }
+      const content = await xmlFile.async('text');
+      const regex = new RegExp(`<Override[^>]*PartName="${partName}"[^>]*/>\\s*`, 'g');
+      if (regex.test(content)) {
+        const updated = content.replace(regex, '');
+        zipManager.writeFile('[Content_Types].xml', updated);
+        logger.debug(`Removed content type for ${partName}`);
+      }
+    });
+    zipManager.addPendingPromise(this.#updateQueue);
+  }
+}
+
+export const contentTypesHelper = new ContentTypesHelper();

package/src/utils/errors.js

@@ -0,0 +1,129 @@
+/**
+ * @fileoverview Custom error classes for node-pptx-templater.
+ *
+ * All errors extend from PPTXError to allow consumers to catch all
+ * library errors with a single catch clause:
+ *
+ *   try {
+ *     await ppt.saveToFile('./out.pptx');
+ *   } catch (err) {
+ *     if (err instanceof PPTXError) {
+ *       // Handle all node-pptx-templater errors
+ *     }
+ *   }
+ */
+
+/**
+ * @class PPTXError
+ * @description Base error class for all node-pptx-templater errors.
+ * @extends Error
+ */
+export class PPTXError extends Error {
+  /**
+   * @param {string} message - Human-readable error description.
+   * @param {Error} [cause] - Original underlying error (for error chaining).
+   */
+  constructor(message, cause) {
+    super(message);
+    this.name = 'PPTXError';
+    if (cause) this.cause = cause;
+
+    // Maintains proper stack trace for where error was thrown (V8 only)
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, this.constructor);
+    }
+  }
+}
+
+/**
+ * @class SlideNotFoundError
+ * @description Thrown when a slide reference cannot be resolved.
+ * @extends PPTXError
+ */
+export class SlideNotFoundError extends PPTXError {
+  /**
+   * @param {string} message
+   */
+  constructor(message) {
+    super(message);
+    this.name = 'SlideNotFoundError';
+  }
+}
+
+/**
+ * @class ChartNotFoundError
+ * @description Thrown when a chart cannot be located in a slide.
+ * @extends PPTXError
+ */
+export class ChartNotFoundError extends PPTXError {
+  /**
+   * @param {string} message
+   */
+  constructor(message) {
+    super(message);
+    this.name = 'ChartNotFoundError';
+  }
+}
+
+/**
+ * @class TableNotFoundError
+ * @description Thrown when a table cannot be located in a slide.
+ * @extends PPTXError
+ */
+export class TableNotFoundError extends PPTXError {
+  /**
+   * @param {string} message
+   */
+  constructor(message) {
+    super(message);
+    this.name = 'TableNotFoundError';
+  }
+}
+
+/**
+ * @class XMLParseError
+ * @description Thrown when XML parsing or building fails.
+ * @extends PPTXError
+ */
+export class XMLParseError extends PPTXError {
+  /**
+   * @param {string} message
+   * @param {Error} [cause]
+   */
+  constructor(message, cause) {
+    super(message, cause);
+    this.name = 'XMLParseError';
+  }
+}
+
+/**
+ * @class InvalidTemplateError
+ * @description Thrown when a PPTX file has an invalid or unsupported structure.
+ * @extends PPTXError
+ */
+export class InvalidTemplateError extends PPTXError {
+  /**
+   * @param {string} message
+   * @param {Error} [cause]
+   */
+  constructor(message, cause) {
+    super(message, cause);
+    this.name = 'InvalidTemplateError';
+  }
+}
+
+/**
+ * @class MediaEmbedError
+ * @description Thrown when a media file cannot be embedded.
+ * @extends PPTXError
+ */
+export class MediaEmbedError extends PPTXError {
+  /**
+   * @param {string} message
+   * @param {Error} [cause]
+   */
+  constructor(message, cause) {
+    super(message, cause);
+    this.name = 'MediaEmbedError';
+  }
+}

package/src/utils/idUtils.js

@@ -0,0 +1,54 @@
+/**
+ * @fileoverview Unique ID generation utilities.
+ * Used for generating shape IDs, slide IDs, etc. in OpenXML.
+ */
+
+import { randomBytes } from 'crypto';
+
+/**
+ * Generates a unique integer ID for use as a shape or slide ID.
+ * OpenXML shape IDs are positive integers unique within a slide.
+ *
+ * @param {number[]} [existingIds] - Array of existing IDs to avoid.
+ * @returns {number} Unique positive integer.
+ */
+export function generateUniqueId(existingIds = []) {
+  const maxId = existingIds.length > 0 ? Math.max(...existingIds) : 0;
+  return maxId + 1;
+}
+
+/**
+ * Generates a UUID v4 string.
+ * Used for chart GUID references and extension URIs in OpenXML.
+ *
+ * @returns {string} UUID v4 string (e.g., '{A1B2C3D4-E5F6-...}')
+ */
+export function generateGuid() {
+  const bytes = randomBytes(16);
+  bytes[6] = (bytes[6] & 0x0f) | 0x40; // Version 4
+  bytes[8] = (bytes[8] & 0x3f) | 0x80; // Variant RFC4122
+
+  const hex = bytes.toString('hex');
+  const guid = [
+    hex.slice(0, 8),
+    hex.slice(8, 12),
+    hex.slice(12, 16),
+    hex.slice(16, 20),
+    hex.slice(20, 32),
+  ].join('-').toUpperCase();
+
+  return `{${guid}}`;
+}
+
+/**
+ * Generates a slide ID (numeric, starts at 256 by convention in OpenXML).
+ * PowerPoint seems to start slide IDs at 256.
+ *
+ * @param {string[]} [existingSlideIds] - Existing slide ID strings.
+ * @returns {string} New slide ID string.
+ */
+export function generateSlideId(existingSlideIds = []) {
+  const existingNums = existingSlideIds.map(id => parseInt(id, 10)).filter(n => !isNaN(n));
+  const maxId = existingNums.length > 0 ? Math.max(...existingNums) : 255;
+  return String(maxId + 1);
+}

package/src/utils/logger.js

@@ -0,0 +1,113 @@
+/**
+ * @fileoverview Logger utility - lightweight structured logging.
+ *
+ * Provides contextual logging with module names.
+ * Respects the PPTX_LOG_LEVEL environment variable.
+ *
+ * Log levels (lowest to highest severity):
+ *   debug → info → warn → error
+ *
+ * Usage:
+ *   const logger = createLogger('MyModule');
+ *   logger.debug('Details here');
+ *   logger.info('Something happened');
+ *   logger.warn('Watch out');
+ *   logger.error('Something failed');
+ *
+ * Environment:
+ *   PPTX_LOG_LEVEL=debug  → show all logs
+ *   PPTX_LOG_LEVEL=info   → show info, warn, error (default)
+ *   PPTX_LOG_LEVEL=warn   → show warn and error only
+ *   PPTX_LOG_LEVEL=error  → show only errors
+ *   PPTX_LOG_LEVEL=silent → suppress all logs
+ */
+
+const LOG_LEVELS = { debug: 0, info: 1, warn: 2, error: 3, silent: 4 };
+
+const currentLevel = LOG_LEVELS[
+  (process.env.PPTX_LOG_LEVEL || 'warn').toLowerCase()
+] ?? LOG_LEVELS.warn;
+
+/**
+ * ANSI color codes for terminal output.
+ */
+const COLORS = {
+  reset: '\x1b[0m',
+  dim: '\x1b[2m',
+  cyan: '\x1b[36m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  red: '\x1b[31m',
+};
+
+/**
+ * Formats the current timestamp as HH:MM:SS.mmm
+ * @returns {string}
+ */
+function timestamp() {
+  return new Date().toISOString().substring(11, 23);
+}
+
+/**
+ * @typedef {Object} Logger
+ * @property {Function} debug - Log debug message.
+ * @property {Function} info - Log info message.
+ * @property {Function} warn - Log warning.
+ * @property {Function} error - Log error.
+ */
+
+/**
+ * Creates a named logger instance.
+ *
+ * @param {string} moduleName - Name of the module (shown in log output).
+ * @returns {Logger}
+ *
+ * @example
+ * const logger = createLogger('SlideManager');
+ * logger.info('Loaded 5 slides');
+ */
+export function createLogger(moduleName) {
+  const isTTY = process.stdout.isTTY;
+
+  const log = (level, levelNum, color, message, ...args) => {
+    if (levelNum < currentLevel) return;
+
+    const prefix = isTTY
+      ? `${COLORS.dim}${timestamp()}${COLORS.reset} ${color}[${level.toUpperCase().padEnd(5)}]${COLORS.reset} ${COLORS.cyan}[${moduleName}]${COLORS.reset}`
+      : `${timestamp()} [${level.toUpperCase().padEnd(5)}] [${moduleName}]`;
+
+    const output = args.length > 0 ? `${message} ${args.map(a => JSON.stringify(a, null, 0)).join(' ')}` : message;
+    const stream = level === 'error' ? process.stderr : process.stdout;
+    stream.write(`${prefix} ${output}\n`);
+  };
+
+  return {
+    /**
+     * Logs a debug-level message. Only shown when PPTX_LOG_LEVEL=debug.
+     * @param {string} message
+     * @param {...*} args
+     */
+    debug: (message, ...args) => log('debug', LOG_LEVELS.debug, COLORS.dim, message, ...args),
+
+    /**
+     * Logs an info-level message.
+     * @param {string} message
+     * @param {...*} args
+     */
+    info: (message, ...args) => log('info', LOG_LEVELS.info, COLORS.green, message, ...args),
+
+    /**
+     * Logs a warning.
+     * @param {string} message
+     * @param {...*} args
+     */
+    warn: (message, ...args) => log('warn', LOG_LEVELS.warn, COLORS.yellow, message, ...args),
+
+    /**
+     * Logs an error.
+     * @param {string} message
+     * @param {...*} args
+     */
+    error: (message, ...args) => log('error', LOG_LEVELS.error, COLORS.red, message, ...args),
+  };
+}

package/src/utils/relationshipUtils.js

@@ -0,0 +1,89 @@
+/**
+ * @fileoverview Relationship ID utilities.
+ *
+ * OpenXML relationship IDs follow the format rId1, rId2, rId3, ...
+ * They must be unique within each .rels file.
+ *
+ * These utilities generate collision-free IDs when adding new relationships.
+ */
+
+/**
+ * Generates the next available relationship ID given an array of existing IDs.
+ * Always uses the format "rId{N}" where N is the next integer after the max.
+ *
+ * @param {string[]} existingIds - Array of existing rId strings (e.g., ['rId1', 'rId2']).
+ * @returns {string} New relationship ID (e.g., 'rId3').
+ *
+ * @example
+ * generateRelationshipId(['rId1', 'rId3'])  // → 'rId4'
+ * generateRelationshipId([])                 // → 'rId1'
+ */
+export function generateRelationshipId(existingIds) {
+  if (!existingIds || existingIds.length === 0) return 'rId1';
+
+  const maxNum = existingIds.reduce((max, id) => {
+    const match = /^rId(\d+)$/.exec(id);
+    if (!match) return max;
+    return Math.max(max, parseInt(match[1], 10));
+  }, 0);
+
+  return `rId${maxNum + 1}`;
+}
+
+/**
+ * Parses a relationship ID string and returns its numeric value.
+ *
+ * @param {string} rId - Relationship ID (e.g., 'rId5').
+ * @returns {number} Numeric value (e.g., 5), or -1 if not a valid rId.
+ *
+ * @example
+ * parseRelationshipId('rId5')  // → 5
+ * parseRelationshipId('foo')   // → -1
+ */
+export function parseRelationshipId(rId) {
+  const match = /^rId(\d+)$/.exec(rId);
+  return match ? parseInt(match[1], 10) : -1;
+}
+
+/**
+ * Checks if a string is a valid relationship ID.
+ *
+ * @param {string} str
+ * @returns {boolean}
+ */
+export function isValidRelationshipId(str) {
+  return /^rId\d+$/.test(str);
+}
+
+/**
+ * Remaps old relationship IDs to new ones within an XML string.
+ * Used when cloning slides to avoid rId conflicts.
+ *
+ * @param {string} xml - XML content containing rId references.
+ * @param {Map<string, string>} idMap - Map of old rId → new rId.
+ * @returns {string} Updated XML with remapped rIds.
+ *
+ * @example
+ * remapRelationshipIds(xml, new Map([['rId1', 'rId5'], ['rId2', 'rId6']]));
+ */
+export function remapRelationshipIds(xml, idMap) {
+  let updated = xml;
+
+  // Sort by length descending to avoid partial replacements (e.g., rId1 replacing part of rId10)
+  const sortedEntries = Array.from(idMap.entries())
+    .sort(([a], [b]) => b.length - a.length);
+
+  for (const [oldId, newId] of sortedEntries) {
+    // Replace rId references in attribute values: r:id="rId1", r:embed="rId1"
+    const pattern = new RegExp(`(r:[a-zA-Z]+=")${oldId}(")|rId="${oldId}(")`, 'g');
+    updated = updated.replace(pattern, (match, pre, post) => {
+      if (pre) return `${pre}${newId}${post}`;
+      return match.replace(oldId, newId);
+    });
+
+    // Simple global replace as fallback
+    updated = updated.split(`"${oldId}"`).join(`"${newId}"`);
+  }
+
+  return updated;
+}

package/src/utils/xmlUtils.js

@@ -0,0 +1,115 @@
+/**
+ * @fileoverview XML validation and repair utilities.
+ *
+ * Provides tools to check if generated XML is well-formed and
+ * attempt automatic repairs for common PPTX corruption issues.
+ */
+
+import { XMLParser } from '../parsers/XMLParser.js';
+
+const parser = new XMLParser();
+
+/**
+ * Validates that an XML string is well-formed.
+ *
+ * @param {string} xmlString - XML to validate.
+ * @returns {{ valid: boolean, error: string|null }} Validation result.
+ *
+ * @example
+ * const { valid, error } = validateXML(xml);
+ * if (!valid) console.error('XML error:', error);
+ */
+export function validateXML(xmlString) {
+  return parser.validate(xmlString);
+}
+
+/**
+ * Attempts to repair common XML corruption issues in PPTX files.
+ *
+ * Known issues this addresses:
+ * 1. Unescaped & in attribute values (e.g., href="a&b" → href="a&b")
+ * 2. Unclosed tags (limited heuristic repair)
+ * 3. Invalid XML characters (removes control chars below 0x20 except tab/LF/CR)
+ *
+ * @param {string} xmlString - Potentially broken XML.
+ * @returns {{ xml: string, repaired: boolean, changes: string[] }}
+ *
+ * @example
+ * const { xml, repaired, changes } = repairXML(brokenXml);
+ * if (repaired) console.log('Repaired:', changes);
+ */
+export function repairXML(xmlString) {
+  const changes = [];
+  let xml = xmlString;
+
+  // Fix 1: Remove invalid XML control characters
+  const before = xml;
+  xml = xml.replace(/[\x00-\x08\x0B\x0C\x0E-\x1F]/g, '');
+  if (xml !== before) changes.push('Removed invalid control characters');
+
+  // Fix 2: Fix unescaped ampersands in text content (not in entities)
+  // Match & not followed by valid entity patterns
+  const fixedAmp = xml.replace(/&(?!amp;|lt;|gt;|quot;|apos;|#\d+;|#x[0-9a-fA-F]+;)/g, '&');
+  if (fixedAmp !== xml) {
+    xml = fixedAmp;
+    changes.push('Escaped unescaped ampersands');
+  }
+
+  // Fix 3: Replace null bytes
+  if (xml.includes('\x00')) {
+    xml = xml.replace(/\x00/g, '');
+    changes.push('Removed null bytes');
+  }
+
+  // Fix 4: Ensure XML declaration is present
+  if (!xml.trimStart().startsWith('<?xml')) {
+    xml = '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>\n' + xml;
+    changes.push('Added missing XML declaration');
+  }
+
+  return {
+    xml,
+    repaired: changes.length > 0,
+    changes,
+  };
+}
+
+/**
+ * Checks if an XML string contains a specific element.
+ *
+ * @param {string} xmlString
+ * @param {string} elementName - Element tag name (e.g., 'a:tbl').
+ * @returns {boolean}
+ */
+export function xmlContainsElement(xmlString, elementName) {
+  return xmlString.includes(`<${elementName}`) || xmlString.includes(`<${elementName}>`);
+}
+
+/**
+ * Counts occurrences of an element in XML.
+ *
+ * @param {string} xmlString
+ * @param {string} elementName
+ * @returns {number}
+ */
+export function countElements(xmlString, elementName) {
+  const pattern = new RegExp(`<${elementName}[\\s>/]`, 'g');
+  return (xmlString.match(pattern) || []).length;
+}
+
+/**
+ * Extracts all attribute values for a given attribute name.
+ *
+ * @param {string} xmlString - XML string to search.
+ * @param {string} attrName - Attribute name (e.g., 'r:id', 'name').
+ * @returns {string[]} Array of attribute values found.
+ */
+export function extractAttributeValues(xmlString, attrName) {
+  const pattern = new RegExp(`${attrName.replace(':', '\\:')}="([^"]*)"`, 'g');
+  const values = [];
+  let match;
+  while ((match = pattern.exec(xmlString)) !== null) {
+    values.push(match[1]);
+  }
+  return values;
+}