docxmlater 10.4.0 → 11.0.4

package/dist/esm/core/DocumentValidator.js

@@ -0,0 +1,222 @@
+import { Paragraph } from '../elements/Paragraph.js';
+import { Table } from '../elements/Table.js';
+import { LIMITS } from '../constants/limits.js';
+import { defaultLogger } from '../utils/logger.js';
+import * as v8 from 'v8';
+export class DocumentValidator {
+    maxMemoryUsagePercent;
+    maxRssMB;
+    useAbsoluteLimit;
+    constructor(maxMemoryUsagePercent = 80, options = {}) {
+        const memoryPercent = options.maxMemoryUsagePercent ?? maxMemoryUsagePercent;
+        if (memoryPercent < 1 || memoryPercent > 100 || !Number.isFinite(memoryPercent)) {
+            throw new Error('maxMemoryUsagePercent must be between 1 and 100');
+        }
+        this.maxMemoryUsagePercent = memoryPercent;
+        this.maxRssMB = options.maxRssMB ?? 2048;
+        this.useAbsoluteLimit = options.useAbsoluteLimit ?? true;
+    }
+    static validateProperties(properties) {
+        const validated = {};
+        if (properties.title !== undefined) {
+            if (typeof properties.title !== 'string') {
+                throw new Error('DocumentProperties.title must be a string');
+            }
+            if (properties.title.length > LIMITS.MAX_STRING_LENGTH) {
+                throw new Error(`DocumentProperties.title exceeds maximum length of ${LIMITS.MAX_STRING_LENGTH} characters`);
+            }
+            validated.title = properties.title;
+        }
+        if (properties.subject !== undefined) {
+            if (typeof properties.subject !== 'string') {
+                throw new Error('DocumentProperties.subject must be a string');
+            }
+            if (properties.subject.length > LIMITS.MAX_STRING_LENGTH) {
+                throw new Error(`DocumentProperties.subject exceeds maximum length of ${LIMITS.MAX_STRING_LENGTH} characters`);
+            }
+            validated.subject = properties.subject;
+        }
+        if (properties.creator !== undefined) {
+            if (typeof properties.creator !== 'string') {
+                throw new Error('DocumentProperties.creator must be a string');
+            }
+            if (properties.creator.length > LIMITS.MAX_STRING_LENGTH) {
+                throw new Error(`DocumentProperties.creator exceeds maximum length of ${LIMITS.MAX_STRING_LENGTH} characters`);
+            }
+            validated.creator = properties.creator;
+        }
+        if (properties.keywords !== undefined) {
+            if (typeof properties.keywords !== 'string') {
+                throw new Error('DocumentProperties.keywords must be a string');
+            }
+            if (properties.keywords.length > LIMITS.MAX_STRING_LENGTH) {
+                throw new Error(`DocumentProperties.keywords exceeds maximum length of ${LIMITS.MAX_STRING_LENGTH} characters`);
+            }
+            validated.keywords = properties.keywords;
+        }
+        if (properties.description !== undefined) {
+            if (typeof properties.description !== 'string') {
+                throw new Error('DocumentProperties.description must be a string');
+            }
+            if (properties.description.length > LIMITS.MAX_STRING_LENGTH) {
+                throw new Error(`DocumentProperties.description exceeds maximum length of ${LIMITS.MAX_STRING_LENGTH} characters`);
+            }
+            validated.description = properties.description;
+        }
+        if (properties.lastModifiedBy !== undefined) {
+            if (typeof properties.lastModifiedBy !== 'string') {
+                throw new Error('DocumentProperties.lastModifiedBy must be a string');
+            }
+            if (properties.lastModifiedBy.length > LIMITS.MAX_STRING_LENGTH) {
+                throw new Error(`DocumentProperties.lastModifiedBy exceeds maximum length of ${LIMITS.MAX_STRING_LENGTH} characters`);
+            }
+            validated.lastModifiedBy = properties.lastModifiedBy;
+        }
+        if (properties.revision !== undefined) {
+            if (typeof properties.revision !== 'number' || !Number.isInteger(properties.revision)) {
+                throw new Error('DocumentProperties.revision must be an integer');
+            }
+            if (properties.revision < 0 || properties.revision > LIMITS.MAX_REVISION) {
+                throw new Error(`DocumentProperties.revision must be between 0 and ${LIMITS.MAX_REVISION}`);
+            }
+            validated.revision = properties.revision;
+        }
+        if (properties.created !== undefined) {
+            if (!(properties.created instanceof Date)) {
+                throw new Error('DocumentProperties.created must be a Date object');
+            }
+            if (!Number.isFinite(properties.created.getTime())) {
+                throw new Error('DocumentProperties.created is an invalid date');
+            }
+            validated.created = properties.created;
+        }
+        if (properties.modified !== undefined) {
+            if (!(properties.modified instanceof Date)) {
+                throw new Error('DocumentProperties.modified must be a Date object');
+            }
+            if (!Number.isFinite(properties.modified.getTime())) {
+                throw new Error('DocumentProperties.modified is an invalid date');
+            }
+            validated.modified = properties.modified;
+        }
+        return validated;
+    }
+    validateBeforeSave(bodyElements) {
+        const paragraphs = bodyElements.filter((el) => el instanceof Paragraph);
+        if (paragraphs.length === 0) {
+            defaultLogger.warn('\nDocXML Save Warning:\n' +
+                'Document has no paragraphs. You are saving an empty document.\n');
+            return;
+        }
+        let totalRuns = 0;
+        let emptyRuns = 0;
+        for (const para of paragraphs) {
+            const runs = para.getRuns();
+            totalRuns += runs.length;
+            for (const run of runs) {
+                if (run.getText().length === 0) {
+                    emptyRuns++;
+                }
+            }
+        }
+        if (totalRuns > 0) {
+            const emptyPercentage = (emptyRuns / totalRuns) * 100;
+            if (emptyPercentage > 90 && emptyRuns > 10) {
+                defaultLogger.warn('\nDocXML Save Warning:\n' +
+                    `You are about to save a document where ${emptyRuns} out of ${totalRuns} runs (${emptyPercentage.toFixed(1)}%) are empty.\n` +
+                    'This may result in a document with no visible text content.\n' +
+                    'If this is unintentional, please review the document before saving.\n');
+            }
+        }
+    }
+    checkMemoryThreshold() {
+        const { heapUsed, external, rss } = process.memoryUsage();
+        const heapStats = v8.getHeapStatistics();
+        const heapLimit = heapStats.heap_size_limit;
+        const heapPercent = (heapUsed / heapLimit) * 100;
+        const heapMB = heapUsed / (1024 * 1024);
+        const heapLimitMB = heapLimit / (1024 * 1024);
+        const rssMB = rss / (1024 * 1024);
+        const externalMB = external / (1024 * 1024);
+        const heapExceeded = heapPercent > this.maxMemoryUsagePercent;
+        const rssExceeded = this.useAbsoluteLimit && rssMB > this.maxRssMB;
+        if (heapExceeded && rssExceeded) {
+            throw new Error(`Memory usage critical:\n` +
+                `  Heap: ${heapMB.toFixed(0)}MB / ${heapLimitMB.toFixed(0)}MB (${heapPercent.toFixed(1)}%)\n` +
+                `  RSS: ${rssMB.toFixed(0)}MB (limit: ${this.maxRssMB}MB)\n` +
+                `  External: ${externalMB.toFixed(0)}MB\n` +
+                `Cannot process document safely. Consider:\n` +
+                `  - Reducing document size (remove/compress images)\n` +
+                `  - Splitting into multiple documents\n` +
+                `  - Increasing memory limits in DocumentOptions\n` +
+                `  - Increasing Node.js heap size (--max-old-space-size)`);
+        }
+        if (heapExceeded && !rssExceeded && this.useAbsoluteLimit) {
+            defaultLogger.warn(`DocXML Memory Warning: Heap usage high (${heapPercent.toFixed(1)}%) ` +
+                `but RSS (${rssMB.toFixed(0)}MB) is below limit. ` +
+                `This might be temporary heap fragmentation.`);
+        }
+    }
+    estimateSize(bodyElements, imageManager) {
+        const paragraphs = bodyElements.filter((el) => el instanceof Paragraph);
+        const tables = bodyElements.filter((el) => el instanceof Table);
+        const paragraphCount = paragraphs.length;
+        const tableCount = tables.length;
+        const imageCount = imageManager.getImageCount();
+        const estimatedXml = paragraphCount * LIMITS.BYTES_PER_PARAGRAPH +
+            tableCount * LIMITS.BYTES_PER_TABLE +
+            LIMITS.BASE_STRUCTURE_BYTES;
+        const imageBytes = imageManager.getTotalSize();
+        const totalBytes = estimatedXml + imageBytes;
+        const totalMB = totalBytes / (1024 * 1024);
+        let warning;
+        if (totalMB > LIMITS.ERROR_SIZE_MB) {
+            warning =
+                `Document size (${totalMB.toFixed(1)}MB) exceeds recommended maximum of ${LIMITS.ERROR_SIZE_MB}MB. ` +
+                    `This may cause memory issues. Consider splitting into multiple documents or optimizing images.`;
+        }
+        else if (totalMB > LIMITS.WARNING_SIZE_MB) {
+            warning =
+                `Document size (${totalMB.toFixed(1)}MB) exceeds ${LIMITS.WARNING_SIZE_MB}MB. ` +
+                    `Large documents may take longer to process and use significant memory.`;
+        }
+        return {
+            paragraphs: paragraphCount,
+            tables: tableCount,
+            images: imageCount,
+            estimatedXmlBytes: estimatedXml,
+            imageBytes,
+            totalEstimatedBytes: totalBytes,
+            totalEstimatedMB: parseFloat(totalMB.toFixed(2)),
+            warning,
+        };
+    }
+    getSizeStats(bodyElements, imageManager) {
+        const estimate = this.estimateSize(bodyElements, imageManager);
+        const warnings = [];
+        if (estimate.warning) {
+            warnings.push(estimate.warning);
+        }
+        const formatBytes = (bytes) => {
+            if (bytes < 1024)
+                return `${bytes} B`;
+            if (bytes < 1024 * 1024)
+                return `${(bytes / 1024).toFixed(1)} KB`;
+            return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+        };
+        return {
+            elements: {
+                paragraphs: estimate.paragraphs,
+                tables: estimate.tables,
+                images: estimate.images,
+            },
+            size: {
+                xml: formatBytes(estimate.estimatedXmlBytes),
+                images: formatBytes(estimate.imageBytes),
+                total: formatBytes(estimate.totalEstimatedBytes),
+            },
+            warnings,
+        };
+    }
+}
+//# sourceMappingURL=DocumentValidator.js.map

package/dist/esm/core/DocumentValidator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"DocumentValidator.js","sourceRoot":"","sources":["../../../src/core/DocumentValidator.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * DocumentValidator - Handles validation of document properties and content\n * Prevents security issues and data corruption\n */\n\nimport { Paragraph } from '../elements/Paragraph.js';\nimport { Table } from '../elements/Table.js';\nimport { ImageManager } from '../elements/ImageManager.js';\nimport type { DocumentProperties } from '../types/document-types.js';\nimport { BodyElement } from './DocumentContent.js';\nimport { LIMITS } from '../constants/limits.js';\nimport { defaultLogger } from '../utils/logger.js';\nimport * as v8 from 'v8';\n\n/**\n * Memory validation options\n */\nexport interface MemoryOptions {\n  /** Maximum memory usage percentage (0-100) before throwing error. Default: 80 */\n  maxMemoryUsagePercent?: number;\n  /** Maximum absolute RSS (Resident Set Size) in MB. Default: 2048 (2GB) */\n  maxRssMB?: number;\n  /** Enable absolute RSS limit checking. Default: true */\n  useAbsoluteLimit?: boolean;\n}\n\n/**\n * Size estimation result\n */\nexport interface SizeEstimate {\n  paragraphs: number;\n  tables: number;\n  images: number;\n  estimatedXmlBytes: number;\n  imageBytes: number;\n  totalEstimatedBytes: number;\n  totalEstimatedMB: number;\n  warning?: string;\n}\n\n/**\n * DocumentValidator handles all validation logic\n */\nexport class DocumentValidator {\n  private maxMemoryUsagePercent: number;\n  private maxRssMB: number;\n  private useAbsoluteLimit: boolean;\n\n  constructor(maxMemoryUsagePercent = 80, options: MemoryOptions = {}) {\n    // Validate maxMemoryUsagePercent\n    const memoryPercent = options.maxMemoryUsagePercent ?? maxMemoryUsagePercent;\n    if (memoryPercent < 1 || memoryPercent > 100 || !Number.isFinite(memoryPercent)) {\n      throw new Error('maxMemoryUsagePercent must be between 1 and 100');\n    }\n    this.maxMemoryUsagePercent = memoryPercent;\n    this.maxRssMB = options.maxRssMB ?? 2048; // Default 2GB\n    this.useAbsoluteLimit = options.useAbsoluteLimit ?? true;\n  }\n\n  /**\n   * Validates and sanitizes document properties\n   * Prevents injection attacks and excessive memory usage\n   * @param properties - Properties to validate\n   * @returns Validated and sanitized properties\n   */\n  static validateProperties(properties: DocumentProperties): DocumentProperties {\n    const validated: DocumentProperties = {};\n\n    // Validate and truncate string properties\n    if (properties.title !== undefined) {\n      if (typeof properties.title !== 'string') {\n        throw new Error('DocumentProperties.title must be a string');\n      }\n      if (properties.title.length > LIMITS.MAX_STRING_LENGTH) {\n        throw new Error(\n          `DocumentProperties.title exceeds maximum length of ${LIMITS.MAX_STRING_LENGTH} characters`\n        );\n      }\n      validated.title = properties.title;\n    }\n\n    if (properties.subject !== undefined) {\n      if (typeof properties.subject !== 'string') {\n        throw new Error('DocumentProperties.subject must be a string');\n      }\n      if (properties.subject.length > LIMITS.MAX_STRING_LENGTH) {\n        throw new Error(\n          `DocumentProperties.subject exceeds maximum length of ${LIMITS.MAX_STRING_LENGTH} characters`\n        );\n      }\n      validated.subject = properties.subject;\n    }\n\n    if (properties.creator !== undefined) {\n      if (typeof properties.creator !== 'string') {\n        throw new Error('DocumentProperties.creator must be a string');\n      }\n      if (properties.creator.length > LIMITS.MAX_STRING_LENGTH) {\n        throw new Error(\n          `DocumentProperties.creator exceeds maximum length of ${LIMITS.MAX_STRING_LENGTH} characters`\n        );\n      }\n      validated.creator = properties.creator;\n    }\n\n    if (properties.keywords !== undefined) {\n      if (typeof properties.keywords !== 'string') {\n        throw new Error('DocumentProperties.keywords must be a string');\n      }\n      if (properties.keywords.length > LIMITS.MAX_STRING_LENGTH) {\n        throw new Error(\n          `DocumentProperties.keywords exceeds maximum length of ${LIMITS.MAX_STRING_LENGTH} characters`\n        );\n      }\n      validated.keywords = properties.keywords;\n    }\n\n    if (properties.description !== undefined) {\n      if (typeof properties.description !== 'string') {\n        throw new Error('DocumentProperties.description must be a string');\n      }\n      if (properties.description.length > LIMITS.MAX_STRING_LENGTH) {\n        throw new Error(\n          `DocumentProperties.description exceeds maximum length of ${LIMITS.MAX_STRING_LENGTH} characters`\n        );\n      }\n      validated.description = properties.description;\n    }\n\n    if (properties.lastModifiedBy !== undefined) {\n      if (typeof properties.lastModifiedBy !== 'string') {\n        throw new Error('DocumentProperties.lastModifiedBy must be a string');\n      }\n      if (properties.lastModifiedBy.length > LIMITS.MAX_STRING_LENGTH) {\n        throw new Error(\n          `DocumentProperties.lastModifiedBy exceeds maximum length of ${LIMITS.MAX_STRING_LENGTH} characters`\n        );\n      }\n      validated.lastModifiedBy = properties.lastModifiedBy;\n    }\n\n    // Validate revision number\n    if (properties.revision !== undefined) {\n      if (typeof properties.revision !== 'number' || !Number.isInteger(properties.revision)) {\n        throw new Error('DocumentProperties.revision must be an integer');\n      }\n      if (properties.revision < 0 || properties.revision > LIMITS.MAX_REVISION) {\n        throw new Error(`DocumentProperties.revision must be between 0 and ${LIMITS.MAX_REVISION}`);\n      }\n      validated.revision = properties.revision;\n    }\n\n    // Validate dates\n    if (properties.created !== undefined) {\n      if (!(properties.created instanceof Date)) {\n        throw new Error('DocumentProperties.created must be a Date object');\n      }\n      if (!Number.isFinite(properties.created.getTime())) {\n        throw new Error('DocumentProperties.created is an invalid date');\n      }\n      validated.created = properties.created;\n    }\n\n    if (properties.modified !== undefined) {\n      if (!(properties.modified instanceof Date)) {\n        throw new Error('DocumentProperties.modified must be a Date object');\n      }\n      if (!Number.isFinite(properties.modified.getTime())) {\n        throw new Error('DocumentProperties.modified is an invalid date');\n      }\n      validated.modified = properties.modified;\n    }\n\n    return validated;\n  }\n\n  /**\n   * Validates that the document has meaningful content before saving\n   * Warns if the document appears to be empty or corrupted\n   */\n  validateBeforeSave(bodyElements: BodyElement[]): void {\n    const paragraphs = bodyElements.filter((el): el is Paragraph => el instanceof Paragraph);\n\n    if (paragraphs.length === 0) {\n      defaultLogger.warn(\n        '\\nDocXML Save Warning:\\n' +\n          'Document has no paragraphs. You are saving an empty document.\\n'\n      );\n      return;\n    }\n\n    // Count runs with text\n    let totalRuns = 0;\n    let emptyRuns = 0;\n\n    for (const para of paragraphs) {\n      const runs = para.getRuns();\n      totalRuns += runs.length;\n\n      for (const run of runs) {\n        if (run.getText().length === 0) {\n          emptyRuns++;\n        }\n      }\n    }\n\n    if (totalRuns > 0) {\n      const emptyPercentage = (emptyRuns / totalRuns) * 100;\n\n      if (emptyPercentage > 90 && emptyRuns > 10) {\n        defaultLogger.warn(\n          '\\nDocXML Save Warning:\\n' +\n            `You are about to save a document where ${emptyRuns} out of ${totalRuns} runs (${emptyPercentage.toFixed(1)}%) are empty.\\n` +\n            'This may result in a document with no visible text content.\\n' +\n            'If this is unintentional, please review the document before saving.\\n'\n        );\n      }\n    }\n  }\n\n  /**\n   * Checks current memory usage and throws if above threshold\n   * Prevents out-of-memory errors by failing early\n   * Uses both heap percentage and absolute RSS limits for better accuracy\n   * @throws {Error} If memory usage exceeds configured limits\n   */\n  checkMemoryThreshold(): void {\n    const { heapUsed, external, rss } = process.memoryUsage();\n    const heapStats = v8.getHeapStatistics();\n    const heapLimit = heapStats.heap_size_limit; // Actual max heap (typically 4GB on 64-bit)\n\n    // Calculate heap usage percentage against the actual limit, not currently allocated\n    const heapPercent = (heapUsed / heapLimit) * 100;\n    const heapMB = heapUsed / (1024 * 1024);\n    const heapLimitMB = heapLimit / (1024 * 1024);\n\n    // Calculate RSS (Resident Set Size - actual memory used by process)\n    const rssMB = rss / (1024 * 1024);\n    const externalMB = external / (1024 * 1024);\n\n    // Check heap percentage (protects against heap fragmentation)\n    const heapExceeded = heapPercent > this.maxMemoryUsagePercent;\n\n    // Check absolute RSS limit (protects against excessive total memory)\n    const rssExceeded = this.useAbsoluteLimit && rssMB > this.maxRssMB;\n\n    // Only throw if BOTH conditions are true (avoids false positives)\n    if (heapExceeded && rssExceeded) {\n      throw new Error(\n        `Memory usage critical:\\n` +\n          `  Heap: ${heapMB.toFixed(0)}MB / ${heapLimitMB.toFixed(0)}MB (${heapPercent.toFixed(1)}%)\\n` +\n          `  RSS: ${rssMB.toFixed(0)}MB (limit: ${this.maxRssMB}MB)\\n` +\n          `  External: ${externalMB.toFixed(0)}MB\\n` +\n          `Cannot process document safely. Consider:\\n` +\n          `  - Reducing document size (remove/compress images)\\n` +\n          `  - Splitting into multiple documents\\n` +\n          `  - Increasing memory limits in DocumentOptions\\n` +\n          `  - Increasing Node.js heap size (--max-old-space-size)`\n      );\n    }\n\n    // Warn if only heap exceeded (might be temporary fragmentation)\n    if (heapExceeded && !rssExceeded && this.useAbsoluteLimit) {\n      defaultLogger.warn(\n        `DocXML Memory Warning: Heap usage high (${heapPercent.toFixed(1)}%) ` +\n          `but RSS (${rssMB.toFixed(0)}MB) is below limit. ` +\n          `This might be temporary heap fragmentation.`\n      );\n    }\n  }\n\n  /**\n   * Estimates the size of the document\n   * Provides breakdown by component and warnings if size is too large\n   * @returns Size estimation with breakdown and optional warning\n   */\n  estimateSize(bodyElements: BodyElement[], imageManager: ImageManager): SizeEstimate {\n    // Count elements\n    const paragraphs = bodyElements.filter((el): el is Paragraph => el instanceof Paragraph);\n    const tables = bodyElements.filter((el): el is Table => el instanceof Table);\n    const paragraphCount = paragraphs.length;\n    const tableCount = tables.length;\n    const imageCount = imageManager.getImageCount();\n\n    // Estimate XML size using documented constants\n    const estimatedXml =\n      paragraphCount * LIMITS.BYTES_PER_PARAGRAPH +\n      tableCount * LIMITS.BYTES_PER_TABLE +\n      LIMITS.BASE_STRUCTURE_BYTES;\n\n    // Get actual image sizes\n    const imageBytes = imageManager.getTotalSize();\n\n    // Total estimate\n    const totalBytes = estimatedXml + imageBytes;\n    const totalMB = totalBytes / (1024 * 1024);\n\n    // Use documented threshold constants\n    let warning: string | undefined;\n\n    if (totalMB > LIMITS.ERROR_SIZE_MB) {\n      warning =\n        `Document size (${totalMB.toFixed(1)}MB) exceeds recommended maximum of ${LIMITS.ERROR_SIZE_MB}MB. ` +\n        `This may cause memory issues. Consider splitting into multiple documents or optimizing images.`;\n    } else if (totalMB > LIMITS.WARNING_SIZE_MB) {\n      warning =\n        `Document size (${totalMB.toFixed(1)}MB) exceeds ${LIMITS.WARNING_SIZE_MB}MB. ` +\n        `Large documents may take longer to process and use significant memory.`;\n    }\n\n    return {\n      paragraphs: paragraphCount,\n      tables: tableCount,\n      images: imageCount,\n      estimatedXmlBytes: estimatedXml,\n      imageBytes,\n      totalEstimatedBytes: totalBytes,\n      totalEstimatedMB: parseFloat(totalMB.toFixed(2)),\n      warning,\n    };\n  }\n\n  /**\n   * Gets size statistics for the document\n   * @returns Size statistics\n   */\n  getSizeStats(\n    bodyElements: BodyElement[],\n    imageManager: ImageManager\n  ): {\n    elements: { paragraphs: number; tables: number; images: number };\n    size: { xml: string; images: string; total: string };\n    warnings: string[];\n  } {\n    const estimate = this.estimateSize(bodyElements, imageManager);\n    const warnings: string[] = [];\n\n    if (estimate.warning) {\n      warnings.push(estimate.warning);\n    }\n\n    // Format sizes for display\n    const formatBytes = (bytes: number): string => {\n      if (bytes < 1024) return `${bytes} B`;\n      if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;\n      return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;\n    };\n\n    return {\n      elements: {\n        paragraphs: estimate.paragraphs,\n        tables: estimate.tables,\n        images: estimate.images,\n      },\n      size: {\n        xml: formatBytes(estimate.estimatedXmlBytes),\n        images: formatBytes(estimate.imageBytes),\n        total: formatBytes(estimate.totalEstimatedBytes),\n      },\n      warnings,\n    };\n  }\n}\n"]}

package/dist/esm/core/ElementRegistry.js

@@ -0,0 +1,24 @@
+import { KeyedRegistry } from '../utils/KeyedRegistry.js';
+class ElementRegistryImpl {
+    inner = new KeyedRegistry('ElementRegistry');
+    register(tag, handler) {
+        this.inner.register(tag, handler);
+    }
+    unregister(tag) {
+        return this.inner.unregister(tag);
+    }
+    has(tag) {
+        return this.inner.has(tag);
+    }
+    get(tag) {
+        return this.inner.get(tag);
+    }
+    registeredTags() {
+        return this.inner.keys();
+    }
+    clear() {
+        this.inner.clear();
+    }
+}
+export const ElementRegistry = new ElementRegistryImpl();
+//# sourceMappingURL=ElementRegistry.js.map

package/dist/esm/core/ElementRegistry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ElementRegistry.js","sourceRoot":"","sources":["../../../src/core/ElementRegistry.ts"],"names":[],"mappings":"AAmBA,OAAO,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAkB1D,MAAM,mBAAmB;IACN,KAAK,GAAG,IAAI,aAAa,CAA0B,iBAAiB,CAAC,CAAC;IAEvF,QAAQ,CAAI,GAAW,EAAE,OAA0B;QACjD,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,GAAG,EAAE,OAAkC,CAAC,CAAC;IAC/D,CAAC;IAED,UAAU,CAAC,GAAW;QACpB,OAAO,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC;IACpC,CAAC;IAED,GAAG,CAAC,GAAW;QACb,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAC7B,CAAC;IAED,GAAG,CAAc,GAAW;QAC1B,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAkC,CAAC;IAC9D,CAAC;IAGD,cAAc;QACZ,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC;IAC3B,CAAC;IAGD,KAAK;QACH,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;IACrB,CAAC;CACF;AAGD,MAAM,CAAC,MAAM,eAAe,GAAG,IAAI,mBAAmB,EAAE,CAAC","sourcesContent":["/**\n * Plugin extension point for custom OOXML element handlers. When the\n * parser encounters an unknown qualified-name child of the body and a\n * handler is registered for that tag, the handler's `parse()` is invoked\n * and the result becomes a `PreservedElement` carrying the original raw\n * XML (so save round-trips byte-for-byte). Handlers that return objects\n * with a `toXml()` method allow consumers to roundtrip through their\n * own model — see DocumentParser.processBodyElement for the contract.\n *\n * Registration is process-global; clear via `clear()` between tests.\n *\n * @example\n * ```typescript\n * ElementRegistry.register('myco:specialBlock', {\n *   parse: (xml) => new MySpecialBlock(xml),\n *   serialize: (element) => (element as MySpecialBlock).toXML(),\n * });\n * ```\n */\nimport { KeyedRegistry } from '../utils/KeyedRegistry.js';\n\nexport interface ElementHandler<E = unknown> {\n  /** Parse the raw XML fragment for this element into a model object. */\n  parse(rawXml: string, context?: ElementParseContext): E;\n  /** Serialize the model object back to raw XML. */\n  serialize(element: E, context?: ElementSerializeContext): string;\n}\n\nexport interface ElementParseContext {\n  /** Path of the OOXML part being parsed (e.g., 'word/document.xml'). */\n  partPath?: string;\n}\n\nexport interface ElementSerializeContext {\n  partPath?: string;\n}\n\nclass ElementRegistryImpl {\n  private readonly inner = new KeyedRegistry<ElementHandler<unknown>>('ElementRegistry');\n\n  register<E>(tag: string, handler: ElementHandler<E>): void {\n    this.inner.register(tag, handler as ElementHandler<unknown>);\n  }\n\n  unregister(tag: string): boolean {\n    return this.inner.unregister(tag);\n  }\n\n  has(tag: string): boolean {\n    return this.inner.has(tag);\n  }\n\n  get<E = unknown>(tag: string): ElementHandler<E> | undefined {\n    return this.inner.get(tag) as ElementHandler<E> | undefined;\n  }\n\n  /** Returns the list of currently-registered tags (snapshot). */\n  registeredTags(): string[] {\n    return this.inner.keys();\n  }\n\n  /** Remove all handlers — primarily for test isolation. */\n  clear(): void {\n    this.inner.clear();\n  }\n}\n\n/** Process-global element registry instance. */\nexport const ElementRegistry = new ElementRegistryImpl();\n"]}

package/dist/esm/core/Relationship.js

@@ -0,0 +1,177 @@
+import { XMLBuilder } from '../xml/XMLBuilder.js';
+export var RelationshipType;
+(function (RelationshipType) {
+    RelationshipType["STYLES"] = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/styles";
+    RelationshipType["NUMBERING"] = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/numbering";
+    RelationshipType["IMAGE"] = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/image";
+    RelationshipType["HEADER"] = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/header";
+    RelationshipType["FOOTER"] = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/footer";
+    RelationshipType["FONT_TABLE"] = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/fontTable";
+    RelationshipType["SETTINGS"] = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/settings";
+    RelationshipType["THEME"] = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/theme";
+    RelationshipType["HYPERLINK"] = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/hyperlink";
+    RelationshipType["COMMENTS"] = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/comments";
+    RelationshipType["FOOTNOTES"] = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/footnotes";
+    RelationshipType["ENDNOTES"] = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/endnotes";
+    RelationshipType["WEB_SETTINGS"] = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/webSettings";
+    RelationshipType["PEOPLE"] = "http://schemas.microsoft.com/office/2011/relationships/people";
+})(RelationshipType || (RelationshipType = {}));
+export class Relationship {
+    id;
+    type;
+    target;
+    targetMode;
+    constructor(properties) {
+        this.id = properties.id;
+        this.type = properties.type;
+        this.target = properties.target;
+        this.targetMode = properties.targetMode || 'Internal';
+        this.validate();
+    }
+    validate() {
+        if (!this.id?.startsWith('rId')) {
+            throw new Error(`Relationship ID must start with 'rId', got '${this.id}'`);
+        }
+        if (!this.type) {
+            throw new Error('Relationship type is required');
+        }
+        if (!this.target) {
+            throw new Error('Relationship target is required');
+        }
+    }
+    getId() {
+        return this.id;
+    }
+    getType() {
+        return this.type;
+    }
+    getTarget() {
+        return this.target;
+    }
+    setTarget(target) {
+        if (!target) {
+            throw new Error('Relationship target cannot be empty');
+        }
+        this.target = target;
+    }
+    getTargetMode() {
+        return this.targetMode;
+    }
+    isExternal() {
+        return this.targetMode === 'External';
+    }
+    toXML() {
+        const escapedId = XMLBuilder.escapeXmlAttribute(this.id);
+        const escapedType = XMLBuilder.escapeXmlAttribute(this.type);
+        const escapedTarget = XMLBuilder.escapeXmlAttribute(this.target);
+        let xml = `  <Relationship Id="${escapedId}" Type="${escapedType}" Target="${escapedTarget}"`;
+        if (this.targetMode === 'External') {
+            xml += ` TargetMode="External"`;
+        }
+        xml += '/>';
+        return xml;
+    }
+    static create(properties) {
+        return new Relationship(properties);
+    }
+    static createStyles(id = 'rId1') {
+        return new Relationship({
+            id,
+            type: RelationshipType.STYLES,
+            target: 'styles.xml',
+        });
+    }
+    static createNumbering(id = 'rId2') {
+        return new Relationship({
+            id,
+            type: RelationshipType.NUMBERING,
+            target: 'numbering.xml',
+        });
+    }
+    static createFontTable(id = 'rId3') {
+        return new Relationship({
+            id,
+            type: RelationshipType.FONT_TABLE,
+            target: 'fontTable.xml',
+        });
+    }
+    static createSettings(id = 'rId4') {
+        return new Relationship({
+            id,
+            type: RelationshipType.SETTINGS,
+            target: 'settings.xml',
+        });
+    }
+    static createWebSettings(id = 'rId5') {
+        return new Relationship({
+            id,
+            type: RelationshipType.WEB_SETTINGS,
+            target: 'webSettings.xml',
+        });
+    }
+    static createTheme(id = 'rId6') {
+        return new Relationship({
+            id,
+            type: RelationshipType.THEME,
+            target: 'theme/theme1.xml',
+        });
+    }
+    static createImage(id, target) {
+        return new Relationship({
+            id,
+            type: RelationshipType.IMAGE,
+            target,
+        });
+    }
+    static createHeader(id, target) {
+        return new Relationship({
+            id,
+            type: RelationshipType.HEADER,
+            target,
+        });
+    }
+    static createFooter(id, target) {
+        return new Relationship({
+            id,
+            type: RelationshipType.FOOTER,
+            target,
+        });
+    }
+    static createHyperlink(id, url) {
+        return new Relationship({
+            id,
+            type: RelationshipType.HYPERLINK,
+            target: url,
+            targetMode: 'External',
+        });
+    }
+    static createComments(id) {
+        return new Relationship({
+            id,
+            type: RelationshipType.COMMENTS,
+            target: 'comments.xml',
+        });
+    }
+    static createFootnotes(id) {
+        return new Relationship({
+            id,
+            type: RelationshipType.FOOTNOTES,
+            target: 'footnotes.xml',
+        });
+    }
+    static createEndnotes(id) {
+        return new Relationship({
+            id,
+            type: RelationshipType.ENDNOTES,
+            target: 'endnotes.xml',
+        });
+    }
+    static createPeople(id) {
+        return new Relationship({
+            id,
+            type: RelationshipType.PEOPLE,
+            target: 'people.xml',
+        });
+    }
+}
+//# sourceMappingURL=Relationship.js.map

package/dist/esm/core/Relationship.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Relationship.js","sourceRoot":"","sources":["../../../src/core/Relationship.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Relationship - Represents an OpenXML relationship\n *\n * Relationships link document parts together (images, headers, footers, styles, etc.)\n * They are stored in _rels/*.xml.rels files throughout the document structure.\n */\n\nimport { XMLBuilder } from '../xml/XMLBuilder.js';\n\n/**\n * Relationship types used in Word documents\n */\nexport enum RelationshipType {\n  /** Link to styles.xml */\n  STYLES = 'http://schemas.openxmlformats.org/officeDocument/2006/relationships/styles',\n\n  /** Link to numbering.xml */\n  NUMBERING = 'http://schemas.openxmlformats.org/officeDocument/2006/relationships/numbering',\n\n  /** Link to an image */\n  IMAGE = 'http://schemas.openxmlformats.org/officeDocument/2006/relationships/image',\n\n  /** Link to a header */\n  HEADER = 'http://schemas.openxmlformats.org/officeDocument/2006/relationships/header',\n\n  /** Link to a footer */\n  FOOTER = 'http://schemas.openxmlformats.org/officeDocument/2006/relationships/footer',\n\n  /** Link to fontTable.xml */\n  FONT_TABLE = 'http://schemas.openxmlformats.org/officeDocument/2006/relationships/fontTable',\n\n  /** Link to settings.xml */\n  SETTINGS = 'http://schemas.openxmlformats.org/officeDocument/2006/relationships/settings',\n\n  /** Link to theme */\n  THEME = 'http://schemas.openxmlformats.org/officeDocument/2006/relationships/theme',\n\n  /** Link to hyperlink */\n  HYPERLINK = 'http://schemas.openxmlformats.org/officeDocument/2006/relationships/hyperlink',\n\n  /** Link to comments.xml */\n  COMMENTS = 'http://schemas.openxmlformats.org/officeDocument/2006/relationships/comments',\n\n  /** Link to footnotes.xml */\n  FOOTNOTES = 'http://schemas.openxmlformats.org/officeDocument/2006/relationships/footnotes',\n\n  /** Link to endnotes.xml */\n  ENDNOTES = 'http://schemas.openxmlformats.org/officeDocument/2006/relationships/endnotes',\n\n  /** Link to web settings */\n  WEB_SETTINGS = 'http://schemas.openxmlformats.org/officeDocument/2006/relationships/webSettings',\n\n  /** Link to people.xml (track changes authors) */\n  PEOPLE = 'http://schemas.microsoft.com/office/2011/relationships/people',\n}\n\n/**\n * Properties for creating a relationship\n */\nexport interface RelationshipProperties {\n  /** Relationship ID (e.g., 'rId1', 'rId2') */\n  id: string;\n\n  /** Relationship type (URL defining the relationship type) */\n  type: string | RelationshipType;\n\n  /** Target path (relative to the source part) */\n  target: string;\n\n  /** Target mode (Internal or External) */\n  targetMode?: 'Internal' | 'External';\n}\n\n/**\n * Represents a single relationship in an OpenXML package\n */\nexport class Relationship {\n  private id: string;\n  private type: string;\n  private target: string;\n  private targetMode: 'Internal' | 'External';\n\n  /**\n   * Creates a new relationship\n   * @param properties Relationship properties\n   */\n  constructor(properties: RelationshipProperties) {\n    this.id = properties.id;\n    this.type = properties.type;\n    this.target = properties.target;\n    this.targetMode = properties.targetMode || 'Internal';\n\n    this.validate();\n  }\n\n  /**\n   * Validates the relationship properties\n   */\n  private validate(): void {\n    if (!this.id?.startsWith('rId')) {\n      throw new Error(`Relationship ID must start with 'rId', got '${this.id}'`);\n    }\n\n    if (!this.type) {\n      throw new Error('Relationship type is required');\n    }\n\n    if (!this.target) {\n      throw new Error('Relationship target is required');\n    }\n  }\n\n  /**\n   * Gets the relationship ID\n   */\n  getId(): string {\n    return this.id;\n  }\n\n  /**\n   * Gets the relationship type\n   */\n  getType(): string {\n    return this.type;\n  }\n\n  /**\n   * Gets the target path\n   */\n  getTarget(): string {\n    return this.target;\n  }\n\n  /**\n   * Sets the target path\n   *\n   * This method allows updating the target of an existing relationship,\n   * which is crucial for properly updating hyperlink URLs without creating\n   * orphaned relationships. Per ECMA-376 §9.2, relationships can be modified\n   * as long as the ID remains the same.\n   *\n   * @param target The new target path or URL\n   */\n  setTarget(target: string): void {\n    if (!target) {\n      throw new Error('Relationship target cannot be empty');\n    }\n    this.target = target;\n  }\n\n  /**\n   * Gets the target mode\n   */\n  getTargetMode(): 'Internal' | 'External' {\n    return this.targetMode;\n  }\n\n  /**\n   * Checks if this relationship is external\n   */\n  isExternal(): boolean {\n    return this.targetMode === 'External';\n  }\n\n  /**\n   * Generates XML for this relationship\n   *\n   * **Security:** All attributes are properly XML-escaped to prevent injection attacks.\n   * Per ECMA-376 Part 2 §9, relationship attributes must be escaped.\n   */\n  toXML(): string {\n    // Escape all attributes to prevent XML injection\n    const escapedId = XMLBuilder.escapeXmlAttribute(this.id);\n    const escapedType = XMLBuilder.escapeXmlAttribute(this.type);\n    const escapedTarget = XMLBuilder.escapeXmlAttribute(this.target);\n\n    let xml = `  <Relationship Id=\"${escapedId}\" Type=\"${escapedType}\" Target=\"${escapedTarget}\"`;\n\n    if (this.targetMode === 'External') {\n      xml += ` TargetMode=\"External\"`;\n    }\n\n    xml += '/>';\n    return xml;\n  }\n\n  /**\n   * Factory method to create a relationship\n   * @param properties Relationship properties\n   */\n  static create(properties: RelationshipProperties): Relationship {\n    return new Relationship(properties);\n  }\n\n  /**\n   * Creates a styles relationship\n   * @param id Relationship ID\n   */\n  static createStyles(id = 'rId1'): Relationship {\n    return new Relationship({\n      id,\n      type: RelationshipType.STYLES,\n      target: 'styles.xml',\n    });\n  }\n\n  /**\n   * Creates a numbering relationship\n   * @param id Relationship ID\n   */\n  static createNumbering(id = 'rId2'): Relationship {\n    return new Relationship({\n      id,\n      type: RelationshipType.NUMBERING,\n      target: 'numbering.xml',\n    });\n  }\n\n  /**\n   * Creates a fontTable relationship\n   * @param id Relationship ID (defaults to 'rId3')\n   */\n  static createFontTable(id = 'rId3'): Relationship {\n    return new Relationship({\n      id,\n      type: RelationshipType.FONT_TABLE,\n      target: 'fontTable.xml',\n    });\n  }\n\n  /**\n   * Creates a settings relationship\n   * @param id Relationship ID (defaults to 'rId4')\n   */\n  static createSettings(id = 'rId4'): Relationship {\n    return new Relationship({\n      id,\n      type: RelationshipType.SETTINGS,\n      target: 'settings.xml',\n    });\n  }\n\n  /**\n   * Creates a webSettings relationship\n   * @param id Relationship ID (defaults to 'rId5')\n   */\n  static createWebSettings(id = 'rId5'): Relationship {\n    return new Relationship({\n      id,\n      type: RelationshipType.WEB_SETTINGS,\n      target: 'webSettings.xml',\n    });\n  }\n\n  /**\n   * Creates a theme relationship\n   * @param id Relationship ID (defaults to 'rId6')\n   */\n  static createTheme(id = 'rId6'): Relationship {\n    return new Relationship({\n      id,\n      type: RelationshipType.THEME,\n      target: 'theme/theme1.xml',\n    });\n  }\n\n  /**\n   * Creates an image relationship\n   * @param id Relationship ID\n   * @param target Image path (e.g., 'media/image1.png')\n   */\n  static createImage(id: string, target: string): Relationship {\n    return new Relationship({\n      id,\n      type: RelationshipType.IMAGE,\n      target,\n    });\n  }\n\n  /**\n   * Creates a header relationship\n   * @param id Relationship ID\n   * @param target Header file path (e.g., 'header1.xml')\n   */\n  static createHeader(id: string, target: string): Relationship {\n    return new Relationship({\n      id,\n      type: RelationshipType.HEADER,\n      target,\n    });\n  }\n\n  /**\n   * Creates a footer relationship\n   * @param id Relationship ID\n   * @param target Footer file path (e.g., 'footer1.xml')\n   */\n  static createFooter(id: string, target: string): Relationship {\n    return new Relationship({\n      id,\n      type: RelationshipType.FOOTER,\n      target,\n    });\n  }\n\n  /**\n   * Creates a hyperlink relationship (external)\n   * @param id Relationship ID\n   * @param url Hyperlink URL\n   */\n  static createHyperlink(id: string, url: string): Relationship {\n    return new Relationship({\n      id,\n      type: RelationshipType.HYPERLINK,\n      target: url,\n      targetMode: 'External',\n    });\n  }\n\n  /**\n   * Creates a comments relationship\n   * @param id Relationship ID (required - use RelationshipManager.generateId())\n   */\n  static createComments(id: string): Relationship {\n    return new Relationship({\n      id,\n      type: RelationshipType.COMMENTS,\n      target: 'comments.xml',\n    });\n  }\n\n  /**\n   * Creates a footnotes relationship\n   * @param id Relationship ID (required - use RelationshipManager.generateId())\n   */\n  static createFootnotes(id: string): Relationship {\n    return new Relationship({\n      id,\n      type: RelationshipType.FOOTNOTES,\n      target: 'footnotes.xml',\n    });\n  }\n\n  /**\n   * Creates an endnotes relationship\n   * @param id Relationship ID (required - use RelationshipManager.generateId())\n   */\n  static createEndnotes(id: string): Relationship {\n    return new Relationship({\n      id,\n      type: RelationshipType.ENDNOTES,\n      target: 'endnotes.xml',\n    });\n  }\n\n  /**\n   * Creates a people relationship (track changes authors)\n   * @param id Relationship ID (required - use RelationshipManager.generateId())\n   */\n  static createPeople(id: string): Relationship {\n    return new Relationship({\n      id,\n      type: RelationshipType.PEOPLE,\n      target: 'people.xml',\n    });\n  }\n}\n"]}