docxmlater 10.4.0 → 11.0.4

package/dist/esm/zip/ZipHandler.js

@@ -0,0 +1,298 @@
+import { ZipReader } from './ZipReader.js';
+import { ZipWriter } from './ZipWriter.js';
+import { DEFAULT_SIZE_LIMITS, } from './types.js';
+import { getGlobalLogger, createScopedLogger } from '../utils/logger.js';
+function getLogger() {
+    return createScopedLogger(getGlobalLogger(), 'ZipHandler');
+}
+export class ZipHandler {
+    reader;
+    writer;
+    mode = 'write';
+    constructor() {
+        this.reader = new ZipReader();
+        this.writer = new ZipWriter();
+    }
+    validateDocumentSize(sizeMB, limits) {
+        const logger = getLogger();
+        const { warningSizeMB, maxSizeMB } = limits;
+        if (maxSizeMB > 0 && sizeMB > maxSizeMB) {
+            logger.error('Document exceeds maximum size', { sizeMB: sizeMB.toFixed(1), maxSizeMB });
+            throw new Error(`Document size (${sizeMB.toFixed(1)}MB) exceeds maximum supported size (${maxSizeMB}MB). ` +
+                `This would likely cause out-of-memory errors. Consider:\n` +
+                `- Compressing/optimizing images\n` +
+                `- Splitting into multiple documents\n` +
+                `- Processing on a machine with more memory\n` +
+                `- Increasing maxSizeMB via LoadOptions.sizeLimits (not recommended)`);
+        }
+        if (warningSizeMB > 0 && sizeMB > warningSizeMB) {
+            logger.warn('Large document detected', { sizeMB: sizeMB.toFixed(1), warningSizeMB });
+        }
+    }
+    getSizeLimits(options) {
+        return {
+            ...DEFAULT_SIZE_LIMITS,
+            ...options.sizeLimits,
+        };
+    }
+    async load(filePath, options = {}) {
+        const logger = getLogger();
+        logger.info('Loading DOCX file', { path: filePath });
+        const { promises: fs } = await import('fs');
+        const stats = await fs.stat(filePath);
+        const sizeMB = stats.size / (1024 * 1024);
+        const limits = this.getSizeLimits(options);
+        this.validateDocumentSize(sizeMB, limits);
+        await this.reader.loadFromFile(filePath, options);
+        const files = this.reader.getAllFiles();
+        this.writer.clear();
+        this.writer.addFiles(files);
+        this.mode = 'modify';
+        logger.info('DOCX file loaded', { fileCount: files.size, sizeMB: sizeMB.toFixed(2) });
+    }
+    async loadFromBuffer(buffer, options = {}) {
+        const logger = getLogger();
+        logger.info('Loading DOCX from buffer', { bufferSize: buffer.length });
+        const sizeMB = buffer.length / (1024 * 1024);
+        const limits = this.getSizeLimits(options);
+        this.validateDocumentSize(sizeMB, limits);
+        await this.reader.loadFromBuffer(buffer, options);
+        const files = this.reader.getAllFiles();
+        this.writer.clear();
+        this.writer.addFiles(files);
+        this.mode = 'modify';
+        logger.info('DOCX buffer loaded', { fileCount: files.size, sizeMB: sizeMB.toFixed(2) });
+    }
+    addFile(filePath, content, options = {}) {
+        this.writer.addFile(filePath, content, options);
+    }
+    addFiles(files, options = {}) {
+        this.writer.addFiles(files, options);
+    }
+    updateFile(filePath, content, options = {}) {
+        if (!this.hasFile(filePath)) {
+            return false;
+        }
+        this.addFile(filePath, content, options);
+        return true;
+    }
+    removeFile(filePath) {
+        return this.writer.removeFile(filePath);
+    }
+    getFile(filePath) {
+        return this.writer.getFile(filePath);
+    }
+    getFileAsString(filePath) {
+        const file = this.getFile(filePath);
+        if (!file) {
+            return undefined;
+        }
+        if (file.isBinary) {
+            throw new Error(`Cannot convert binary file "${filePath}" to string. ` +
+                `Binary files (images, fonts, etc.) cannot be safely converted to UTF-8 strings. ` +
+                `Use getFileAsBuffer() instead to access the raw bytes.`);
+        }
+        if (Buffer.isBuffer(file.content)) {
+            return file.content.toString('utf8');
+        }
+        return file.content;
+    }
+    getFileAsBuffer(filePath) {
+        const file = this.getFile(filePath);
+        if (!file) {
+            return undefined;
+        }
+        if (Buffer.isBuffer(file.content)) {
+            return file.content;
+        }
+        return Buffer.from(file.content, 'utf8');
+    }
+    getAllFiles() {
+        return this.writer.getAllFiles();
+    }
+    getFilePaths() {
+        return this.writer.getFilePaths();
+    }
+    hasFile(filePath) {
+        return this.writer.hasFile(filePath);
+    }
+    getFileCount() {
+        return this.writer.getFileCount();
+    }
+    renameFile(oldPath, newPath) {
+        const file = this.getFile(oldPath);
+        if (!file) {
+            return false;
+        }
+        this.addFile(newPath, file.content, {
+            binary: file.isBinary,
+            date: file.date,
+        });
+        this.removeFile(oldPath);
+        return true;
+    }
+    copyFile(srcPath, destPath) {
+        const file = this.getFile(srcPath);
+        if (!file) {
+            return false;
+        }
+        this.addFile(destPath, file.content, {
+            binary: file.isBinary,
+            date: file.date,
+        });
+        return true;
+    }
+    moveFile(srcPath, destPath) {
+        if (!this.copyFile(srcPath, destPath)) {
+            return false;
+        }
+        this.removeFile(srcPath);
+        return true;
+    }
+    existsOrThrow(filePath) {
+        if (!this.hasFile(filePath)) {
+            throw new Error(`File not found in archive: ${filePath}`);
+        }
+    }
+    removeFiles(filePaths) {
+        let count = 0;
+        for (const filePath of filePaths) {
+            if (this.removeFile(filePath)) {
+                count++;
+            }
+        }
+        return count;
+    }
+    getFilesByExtension(extension) {
+        const ext = extension.startsWith('.') ? extension : `.${extension}`;
+        const files = [];
+        for (const [path, file] of this.getAllFiles()) {
+            if (path.toLowerCase().endsWith(ext.toLowerCase())) {
+                files.push(file);
+            }
+        }
+        return files;
+    }
+    getTotalSize() {
+        let totalSize = 0;
+        for (const file of this.getAllFiles().values()) {
+            totalSize += file.size;
+        }
+        return totalSize;
+    }
+    getStats() {
+        let textCount = 0;
+        let binaryCount = 0;
+        const totalSize = this.getTotalSize();
+        const fileCount = this.getFileCount();
+        for (const file of this.getAllFiles().values()) {
+            if (file.isBinary) {
+                binaryCount++;
+            }
+            else {
+                textCount++;
+            }
+        }
+        return {
+            fileCount,
+            totalSize,
+            textFileCount: textCount,
+            binaryFileCount: binaryCount,
+            avgFileSize: fileCount > 0 ? Math.round(totalSize / fileCount) : 0,
+        };
+    }
+    isEmpty() {
+        return this.getFileCount() === 0;
+    }
+    getTextFiles() {
+        const files = [];
+        for (const file of this.getAllFiles().values()) {
+            if (!file.isBinary) {
+                files.push(file);
+            }
+        }
+        return files;
+    }
+    getBinaryFiles() {
+        const files = [];
+        for (const file of this.getAllFiles().values()) {
+            if (file.isBinary) {
+                files.push(file);
+            }
+        }
+        return files;
+    }
+    getMediaFiles() {
+        const files = [];
+        for (const [path, file] of this.getAllFiles()) {
+            if (path.startsWith('word/media/')) {
+                files.push(file);
+            }
+        }
+        return files;
+    }
+    async exportFile(internalPath, outputPath) {
+        const { promises: fs } = await import('fs');
+        const content = this.getFileAsBuffer(internalPath);
+        if (!content) {
+            throw new Error(`File not found in archive: ${internalPath}`);
+        }
+        await fs.writeFile(outputPath, content);
+    }
+    async importFile(sourcePath, internalPath, options = {}) {
+        const { promises: fs } = await import('fs');
+        const content = await fs.readFile(sourcePath);
+        this.addFile(internalPath, content, {
+            ...options,
+            binary: options.binary !== undefined ? options.binary : true,
+        });
+    }
+    async save(filePath, options = {}) {
+        const logger = getLogger();
+        logger.info('Saving DOCX file', { path: filePath, fileCount: this.getFileCount() });
+        await this.writer.saveToFile(filePath, options);
+        logger.info('DOCX file saved', { path: filePath });
+    }
+    async toBuffer(options = {}) {
+        const logger = getLogger();
+        logger.info('Generating DOCX buffer', { fileCount: this.getFileCount() });
+        const buffer = await this.writer.toBuffer(options);
+        logger.info('DOCX buffer generated', { bufferSize: buffer.length });
+        return buffer;
+    }
+    validate() {
+        const logger = getLogger();
+        logger.info('Validating DOCX structure');
+        this.writer.validate();
+        logger.info('DOCX structure valid');
+    }
+    clear() {
+        this.reader.clear();
+        this.writer.clear();
+        this.mode = 'write';
+    }
+    getMode() {
+        return this.mode;
+    }
+    isLoaded() {
+        return this.reader.isLoaded();
+    }
+    clone() {
+        const newHandler = new ZipHandler();
+        newHandler.writer = this.writer.clone();
+        newHandler.mode = this.mode;
+        return newHandler;
+    }
+    static async modify(inputPath, outputPath, modifier, loadOptions = {}, saveOptions = {}) {
+        const handler = new ZipHandler();
+        await handler.load(inputPath, loadOptions);
+        await modifier(handler);
+        await handler.save(outputPath, saveOptions);
+    }
+    static async create(outputPath, files, saveOptions = {}) {
+        const handler = new ZipHandler();
+        handler.addFiles(files);
+        await handler.save(outputPath, saveOptions);
+    }
+}
+//# sourceMappingURL=ZipHandler.js.map

package/dist/esm/zip/ZipHandler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ZipHandler.js","sourceRoot":"","sources":["../../../src/zip/ZipHandler.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * ZipHandler - Main facade for ZIP archive operations\n * Provides a unified interface for reading and writing DOCX files\n */\n\nimport { ZipReader } from './ZipReader.js';\nimport { ZipWriter } from './ZipWriter.js';\nimport {\n  ZipFile,\n  FileMap,\n  LoadOptions,\n  SaveOptions,\n  AddFileOptions,\n  SizeLimitOptions,\n  DEFAULT_SIZE_LIMITS,\n} from './types.js';\nimport { getGlobalLogger, createScopedLogger, ILogger } from '../utils/logger.js';\n\n// Create scoped logger for ZipHandler operations\nfunction getLogger(): ILogger {\n  return createScopedLogger(getGlobalLogger(), 'ZipHandler');\n}\n\n/**\n * Main class for handling ZIP archives (DOCX files)\n * Combines reading and writing operations into a single interface\n */\nexport class ZipHandler {\n  private reader: ZipReader;\n  private writer: ZipWriter;\n  private mode: 'read' | 'write' | 'modify' = 'write';\n\n  constructor() {\n    this.reader = new ZipReader();\n    this.writer = new ZipWriter();\n  }\n\n  // ==================== SIZE VALIDATION ====================\n\n  /**\n   * Validates document size against configured limits\n   * @param sizeMB - Size in megabytes\n   * @param limits - Size limit options (merged with defaults)\n   * @throws Error if size exceeds maximum\n   */\n  private validateDocumentSize(sizeMB: number, limits: Required<SizeLimitOptions>): void {\n    const logger = getLogger();\n    const { warningSizeMB, maxSizeMB } = limits;\n\n    // Check maximum size (if enabled)\n    if (maxSizeMB > 0 && sizeMB > maxSizeMB) {\n      logger.error('Document exceeds maximum size', { sizeMB: sizeMB.toFixed(1), maxSizeMB });\n      throw new Error(\n        `Document size (${sizeMB.toFixed(1)}MB) exceeds maximum supported size (${maxSizeMB}MB). ` +\n          `This would likely cause out-of-memory errors. Consider:\\n` +\n          `- Compressing/optimizing images\\n` +\n          `- Splitting into multiple documents\\n` +\n          `- Processing on a machine with more memory\\n` +\n          `- Increasing maxSizeMB via LoadOptions.sizeLimits (not recommended)`\n      );\n    }\n\n    // Warn on large files (if enabled)\n    if (warningSizeMB > 0 && sizeMB > warningSizeMB) {\n      logger.warn('Large document detected', { sizeMB: sizeMB.toFixed(1), warningSizeMB });\n    }\n  }\n\n  /**\n   * Gets merged size limits from options and defaults\n   * @param options - Load options that may contain size limits\n   * @returns Merged size limits with all values defined\n   */\n  private getSizeLimits(options: LoadOptions): Required<SizeLimitOptions> {\n    return {\n      ...DEFAULT_SIZE_LIMITS,\n      ...options.sizeLimits,\n    };\n  }\n\n  // ==================== LOADING ====================\n\n  /**\n   * Loads a DOCX file from the filesystem\n   * @param filePath - Path to the DOCX file\n   * @param options - Load options (including configurable size limits)\n   */\n  async load(filePath: string, options: LoadOptions = {}): Promise<void> {\n    const logger = getLogger();\n    logger.info('Loading DOCX file', { path: filePath });\n\n    // Check file size before loading\n    const { promises: fs } = await import('fs');\n    const stats = await fs.stat(filePath);\n    const sizeMB = stats.size / (1024 * 1024);\n\n    // Validate against configurable limits\n    const limits = this.getSizeLimits(options);\n    this.validateDocumentSize(sizeMB, limits);\n\n    await this.reader.loadFromFile(filePath, options);\n\n    // Copy all files from reader to writer for modification\n    const files = this.reader.getAllFiles();\n    this.writer.clear();\n    this.writer.addFiles(files);\n\n    this.mode = 'modify';\n    logger.info('DOCX file loaded', { fileCount: files.size, sizeMB: sizeMB.toFixed(2) });\n  }\n\n  /**\n   * Loads a DOCX file from a buffer\n   * @param buffer - Buffer containing the DOCX data\n   * @param options - Load options (including configurable size limits)\n   */\n  async loadFromBuffer(buffer: Buffer, options: LoadOptions = {}): Promise<void> {\n    const logger = getLogger();\n    logger.info('Loading DOCX from buffer', { bufferSize: buffer.length });\n\n    // Check buffer size before loading\n    const sizeMB = buffer.length / (1024 * 1024);\n\n    // Validate against configurable limits\n    const limits = this.getSizeLimits(options);\n    this.validateDocumentSize(sizeMB, limits);\n\n    await this.reader.loadFromBuffer(buffer, options);\n\n    // Copy all files from reader to writer for modification\n    const files = this.reader.getAllFiles();\n    this.writer.clear();\n    this.writer.addFiles(files);\n\n    this.mode = 'modify';\n    logger.info('DOCX buffer loaded', { fileCount: files.size, sizeMB: sizeMB.toFixed(2) });\n  }\n\n  // ==================== FILE OPERATIONS ====================\n\n  /**\n   * Adds a file to the archive\n   * @param filePath - Path where the file will be stored in the archive\n   * @param content - File content (string or Buffer)\n   * @param options - Options for adding the file\n   */\n  addFile(filePath: string, content: string | Buffer, options: AddFileOptions = {}): void {\n    this.writer.addFile(filePath, content, options);\n  }\n\n  /**\n   * Adds multiple files to the archive\n   * @param files - Map of file paths to contents\n   * @param options - Options for adding files\n   */\n  addFiles(files: FileMap, options: AddFileOptions = {}): void {\n    this.writer.addFiles(files, options);\n  }\n\n  /**\n   * Updates an existing file in the archive\n   * @param filePath - Path to the file to update\n   * @param content - New content\n   * @param options - Options for updating the file\n   * @returns True if the file was updated, false if it didn't exist\n   */\n  updateFile(filePath: string, content: string | Buffer, options: AddFileOptions = {}): boolean {\n    if (!this.hasFile(filePath)) {\n      return false;\n    }\n    this.addFile(filePath, content, options);\n    return true;\n  }\n\n  /**\n   * Removes a file from the archive\n   * @param filePath - Path to the file to remove\n   * @returns True if the file was removed, false if it didn't exist\n   */\n  removeFile(filePath: string): boolean {\n    return this.writer.removeFile(filePath);\n  }\n\n  /**\n   * Gets a specific file from the archive\n   * @param filePath - Path to the file within the archive\n   * @returns The file data, or undefined if not found\n   */\n  getFile(filePath: string): ZipFile | undefined {\n    return this.writer.getFile(filePath);\n  }\n\n  /**\n   * Gets the content of a specific file as a string\n   * @param filePath - Path to the file within the archive\n   * @returns The file content as a UTF-8 string, or undefined if not found\n   * @throws Error if attempting to convert a binary file to string (Issue #12 fix)\n   *\n   * **Encoding Note:**\n   * - Returns UTF-8 decoded string content for text files\n   * - All text content in DOCX files must be UTF-8 per OpenXML specification\n   * - For binary files (images, fonts), throws an error to prevent garbage output\n   * - Use getFileAsBuffer() for binary files instead\n   */\n  getFileAsString(filePath: string): string | undefined {\n    const file = this.getFile(filePath);\n    if (!file) {\n      return undefined;\n    }\n\n    // Issue #12 fix: Prevent converting binary files to UTF-8 strings\n    // This produces garbage output for images, fonts, etc.\n    if (file.isBinary) {\n      throw new Error(\n        `Cannot convert binary file \"${filePath}\" to string. ` +\n          `Binary files (images, fonts, etc.) cannot be safely converted to UTF-8 strings. ` +\n          `Use getFileAsBuffer() instead to access the raw bytes.`\n      );\n    }\n\n    // After ZipWriter fix (Issue #4), check actual content type instead of flag\n    // Content from ZipWriter is always Buffer, content from ZipReader may be string\n    if (Buffer.isBuffer(file.content)) {\n      // Convert buffer to UTF-8 string\n      return file.content.toString('utf8');\n    }\n\n    return file.content;\n  }\n\n  /**\n   * Gets the content of a specific file as a buffer\n   * @param filePath - Path to the file within the archive\n   * @returns The file content as a Buffer, or undefined if not found\n   *\n   * **Encoding Note:**\n   * - Returns Buffer with UTF-8 encoded content for text files\n   * - For binary files, returns raw bytes unchanged\n   * - All text content is guaranteed to be UTF-8 encoded\n   */\n  getFileAsBuffer(filePath: string): Buffer | undefined {\n    const file = this.getFile(filePath);\n    if (!file) {\n      return undefined;\n    }\n\n    // After ZipWriter fix (Issue #4), check actual content type instead of flag\n    // Content from ZipWriter is always Buffer, content from ZipReader may be string\n    if (Buffer.isBuffer(file.content)) {\n      return file.content;\n    }\n\n    // Encode string content as UTF-8 Buffer (for content from ZipReader)\n    return Buffer.from(file.content, 'utf8');\n  }\n\n  /**\n   * Gets all files from the archive\n   * @returns Map of file paths to file data\n   */\n  getAllFiles(): FileMap {\n    return this.writer.getAllFiles();\n  }\n\n  /**\n   * Gets a list of all file paths in the archive\n   * @returns Array of file paths\n   */\n  getFilePaths(): string[] {\n    return this.writer.getFilePaths();\n  }\n\n  /**\n   * Checks if a file exists in the archive\n   * @param filePath - Path to check\n   * @returns True if the file exists\n   */\n  hasFile(filePath: string): boolean {\n    return this.writer.hasFile(filePath);\n  }\n\n  /**\n   * Gets the number of files in the archive\n   * @returns Number of files\n   */\n  getFileCount(): number {\n    return this.writer.getFileCount();\n  }\n\n  // ==================== HELPER METHODS ====================\n\n  /**\n   * Renames a file in the archive\n   * @param oldPath - Current path of the file\n   * @param newPath - New path for the file\n   * @returns True if the file was renamed, false if it didn't exist\n   */\n  renameFile(oldPath: string, newPath: string): boolean {\n    const file = this.getFile(oldPath);\n    if (!file) {\n      return false;\n    }\n    this.addFile(newPath, file.content, {\n      binary: file.isBinary,\n      date: file.date,\n    });\n    this.removeFile(oldPath);\n    return true;\n  }\n\n  /**\n   * Copies a file within the archive\n   * @param srcPath - Source file path\n   * @param destPath - Destination file path\n   * @returns True if the file was copied, false if source didn't exist\n   */\n  copyFile(srcPath: string, destPath: string): boolean {\n    const file = this.getFile(srcPath);\n    if (!file) {\n      return false;\n    }\n    this.addFile(destPath, file.content, {\n      binary: file.isBinary,\n      date: file.date,\n    });\n    return true;\n  }\n\n  /**\n   * Moves a file within the archive (copy and delete)\n   * @param srcPath - Source file path\n   * @param destPath - Destination file path\n   * @returns True if the file was moved, false if source didn't exist\n   */\n  moveFile(srcPath: string, destPath: string): boolean {\n    if (!this.copyFile(srcPath, destPath)) {\n      return false;\n    }\n    this.removeFile(srcPath);\n    return true;\n  }\n\n  /**\n   * Checks if a file exists, throws if it doesn't\n   * @param filePath - Path to check\n   * @throws {Error} If file doesn't exist\n   */\n  existsOrThrow(filePath: string): void {\n    if (!this.hasFile(filePath)) {\n      throw new Error(`File not found in archive: ${filePath}`);\n    }\n  }\n\n  /**\n   * Removes multiple files from the archive\n   * @param filePaths - Array of file paths to remove\n   * @returns Number of files successfully removed\n   */\n  removeFiles(filePaths: string[]): number {\n    let count = 0;\n    for (const filePath of filePaths) {\n      if (this.removeFile(filePath)) {\n        count++;\n      }\n    }\n    return count;\n  }\n\n  /**\n   * Gets all files with a specific extension\n   * @param extension - File extension (with or without leading dot)\n   * @returns Array of files with the specified extension\n   */\n  getFilesByExtension(extension: string): ZipFile[] {\n    const ext = extension.startsWith('.') ? extension : `.${extension}`;\n    const files: ZipFile[] = [];\n    for (const [path, file] of this.getAllFiles()) {\n      if (path.toLowerCase().endsWith(ext.toLowerCase())) {\n        files.push(file);\n      }\n    }\n    return files;\n  }\n\n  /**\n   * Gets the total uncompressed size of all files in the archive\n   * @returns Total size in bytes\n   */\n  getTotalSize(): number {\n    let totalSize = 0;\n    for (const file of this.getAllFiles().values()) {\n      totalSize += file.size;\n    }\n    return totalSize;\n  }\n\n  /**\n   * Gets comprehensive statistics about the archive\n   * @returns Statistics object\n   */\n  getStats(): {\n    fileCount: number;\n    totalSize: number;\n    textFileCount: number;\n    binaryFileCount: number;\n    avgFileSize: number;\n  } {\n    let textCount = 0;\n    let binaryCount = 0;\n    const totalSize = this.getTotalSize();\n    const fileCount = this.getFileCount();\n\n    for (const file of this.getAllFiles().values()) {\n      if (file.isBinary) {\n        binaryCount++;\n      } else {\n        textCount++;\n      }\n    }\n\n    return {\n      fileCount,\n      totalSize,\n      textFileCount: textCount,\n      binaryFileCount: binaryCount,\n      avgFileSize: fileCount > 0 ? Math.round(totalSize / fileCount) : 0,\n    };\n  }\n\n  /**\n   * Checks if the archive is empty\n   * @returns True if the archive has no files\n   */\n  isEmpty(): boolean {\n    return this.getFileCount() === 0;\n  }\n\n  /**\n   * Gets all text (non-binary) files from the archive\n   * @returns Array of text files\n   */\n  getTextFiles(): ZipFile[] {\n    const files: ZipFile[] = [];\n    for (const file of this.getAllFiles().values()) {\n      if (!file.isBinary) {\n        files.push(file);\n      }\n    }\n    return files;\n  }\n\n  /**\n   * Gets all binary files from the archive\n   * @returns Array of binary files\n   */\n  getBinaryFiles(): ZipFile[] {\n    const files: ZipFile[] = [];\n    for (const file of this.getAllFiles().values()) {\n      if (file.isBinary) {\n        files.push(file);\n      }\n    }\n    return files;\n  }\n\n  /**\n   * Gets all media files from the word/media/ directory\n   * @returns Array of media files\n   */\n  getMediaFiles(): ZipFile[] {\n    const files: ZipFile[] = [];\n    for (const [path, file] of this.getAllFiles()) {\n      if (path.startsWith('word/media/')) {\n        files.push(file);\n      }\n    }\n    return files;\n  }\n\n  /**\n   * Exports a file from the archive to the filesystem\n   * @param internalPath - Path of the file within the archive\n   * @param outputPath - Path where the file will be saved\n   */\n  async exportFile(internalPath: string, outputPath: string): Promise<void> {\n    const { promises: fs } = await import('fs');\n    const content = this.getFileAsBuffer(internalPath);\n    if (!content) {\n      throw new Error(`File not found in archive: ${internalPath}`);\n    }\n    await fs.writeFile(outputPath, content);\n  }\n\n  /**\n   * Imports a file from the filesystem into the archive\n   * @param sourcePath - Path to the file on filesystem\n   * @param internalPath - Path where the file will be stored in archive\n   * @param options - Options for adding the file\n   */\n  async importFile(\n    sourcePath: string,\n    internalPath: string,\n    options: AddFileOptions = {}\n  ): Promise<void> {\n    const { promises: fs } = await import('fs');\n    const content = await fs.readFile(sourcePath);\n    this.addFile(internalPath, content, {\n      ...options,\n      binary: options.binary !== undefined ? options.binary : true,\n    });\n  }\n\n  // ==================== SAVING ====================\n\n  /**\n   * Saves the archive to a file\n   * @param filePath - Path where the file will be saved\n   * @param options - Save options\n   */\n  async save(filePath: string, options: SaveOptions = {}): Promise<void> {\n    const logger = getLogger();\n    logger.info('Saving DOCX file', { path: filePath, fileCount: this.getFileCount() });\n    await this.writer.saveToFile(filePath, options);\n    logger.info('DOCX file saved', { path: filePath });\n  }\n\n  /**\n   * Generates the ZIP archive as a buffer\n   * @param options - Save options\n   * @returns Buffer containing the ZIP archive\n   */\n  async toBuffer(options: SaveOptions = {}): Promise<Buffer> {\n    const logger = getLogger();\n    logger.info('Generating DOCX buffer', { fileCount: this.getFileCount() });\n    const buffer = await this.writer.toBuffer(options);\n    logger.info('DOCX buffer generated', { bufferSize: buffer.length });\n    return buffer;\n  }\n\n  // ==================== VALIDATION ====================\n\n  /**\n   * Validates the DOCX structure\n   * @throws {MissingRequiredFileError} If required files are missing\n   */\n  validate(): void {\n    const logger = getLogger();\n    logger.info('Validating DOCX structure');\n    this.writer.validate();\n    logger.info('DOCX structure valid');\n  }\n\n  // ==================== UTILITY ====================\n\n  /**\n   * Creates a new empty archive\n   */\n  clear(): void {\n    this.reader.clear();\n    this.writer.clear();\n    this.mode = 'write';\n  }\n\n  /**\n   * Gets the current mode of the handler\n   * @returns Current mode ('read', 'write', or 'modify')\n   */\n  getMode(): 'read' | 'write' | 'modify' {\n    return this.mode;\n  }\n\n  /**\n   * Checks if the archive has been loaded\n   * @returns True if loaded\n   */\n  isLoaded(): boolean {\n    return this.reader.isLoaded();\n  }\n\n  /**\n   * Creates a clone of this handler with all its files\n   * @returns A new ZipHandler instance with the same files\n   */\n  clone(): ZipHandler {\n    const newHandler = new ZipHandler();\n    newHandler.writer = this.writer.clone();\n    newHandler.mode = this.mode;\n    return newHandler;\n  }\n\n  // ==================== CONVENIENCE METHODS ====================\n\n  /**\n   * Reads a DOCX file, modifies it, and saves it back\n   * @param inputPath - Path to the input DOCX file\n   * @param outputPath - Path to save the modified file\n   * @param modifier - Function that modifies the handler\n   * @param loadOptions - Options for loading\n   * @param saveOptions - Options for saving\n   */\n  static async modify(\n    inputPath: string,\n    outputPath: string,\n    modifier: (handler: ZipHandler) => void | Promise<void>,\n    loadOptions: LoadOptions = {},\n    saveOptions: SaveOptions = {}\n  ): Promise<void> {\n    const handler = new ZipHandler();\n    await handler.load(inputPath, loadOptions);\n    await modifier(handler);\n    await handler.save(outputPath, saveOptions);\n  }\n\n  /**\n   * Creates a new DOCX file with the provided files\n   * @param outputPath - Path to save the new file\n   * @param files - Map of file paths to contents\n   * @param saveOptions - Options for saving\n   */\n  static async create(\n    outputPath: string,\n    files: FileMap,\n    saveOptions: SaveOptions = {}\n  ): Promise<void> {\n    const handler = new ZipHandler();\n    handler.addFiles(files);\n    await handler.save(outputPath, saveOptions);\n  }\n}\n"]}

package/dist/esm/zip/ZipReader.js

@@ -0,0 +1,147 @@
+import JSZip from 'jszip';
+import { promises as fs } from 'fs';
+import { DocxNotFoundError, InvalidDocxError, CorruptedArchiveError, FileOperationError, } from './errors.js';
+import { validateDocxStructure, isBinaryFile, normalizePath, isValidZipBuffer, } from '../utils/validation.js';
+export class ZipReader {
+    zip = null;
+    files = new Map();
+    loaded = false;
+    async loadFromFile(filePath, options = {}) {
+        try {
+            try {
+                await fs.access(filePath);
+            }
+            catch {
+                throw new DocxNotFoundError(filePath);
+            }
+            const buffer = await fs.readFile(filePath);
+            await this.loadFromBuffer(buffer, options);
+        }
+        catch (error) {
+            if (error instanceof DocxNotFoundError) {
+                throw error;
+            }
+            const message = error instanceof Error ? error.message : String(error);
+            throw new FileOperationError('read', message);
+        }
+    }
+    async loadFromBuffer(buffer, options = {}) {
+        const { validate = true } = options;
+        try {
+            if (!isValidZipBuffer(buffer)) {
+                throw new InvalidDocxError('File is not a valid ZIP archive');
+            }
+            this.zip = await JSZip.loadAsync(buffer);
+            await this.extractFiles();
+            if (validate) {
+                this.validate();
+            }
+            this.loaded = true;
+        }
+        catch (error) {
+            if (error instanceof InvalidDocxError) {
+                throw error;
+            }
+            const message = error instanceof Error ? error.message : String(error);
+            throw new CorruptedArchiveError(message);
+        }
+    }
+    async extractFiles() {
+        if (!this.zip) {
+            throw new Error('ZIP archive not loaded');
+        }
+        this.files.clear();
+        const filePaths = Object.keys(this.zip.files).filter((path) => !this.zip.files[path].dir);
+        for (const filePath of filePaths) {
+            const normalizedPath = normalizePath(filePath);
+            const zipObject = this.zip.files[filePath];
+            if (!zipObject) {
+                continue;
+            }
+            const isBinary = isBinaryFile(normalizedPath);
+            let content;
+            if (isBinary) {
+                content = await zipObject.async('nodebuffer');
+            }
+            else {
+                content = await zipObject.async('string');
+            }
+            const date = zipObject.date;
+            this.files.set(normalizedPath, {
+                path: normalizedPath,
+                content,
+                isBinary,
+                size: isBinary ? content.length : content.length,
+                date,
+            });
+        }
+    }
+    validate() {
+        const filePaths = Array.from(this.files.keys());
+        validateDocxStructure(filePaths);
+    }
+    getFile(filePath) {
+        this.ensureLoaded();
+        const normalizedPath = normalizePath(filePath);
+        return this.files.get(normalizedPath);
+    }
+    getFileAsString(filePath) {
+        const file = this.getFile(filePath);
+        if (!file) {
+            return undefined;
+        }
+        if (Buffer.isBuffer(file.content)) {
+            return file.content.toString('utf8');
+        }
+        return file.content;
+    }
+    getFileAsBuffer(filePath) {
+        const file = this.getFile(filePath);
+        if (!file) {
+            return undefined;
+        }
+        if (Buffer.isBuffer(file.content)) {
+            return file.content;
+        }
+        return Buffer.from(file.content, 'utf8');
+    }
+    getAllFiles() {
+        this.ensureLoaded();
+        return new Map(this.files);
+    }
+    getFilePaths() {
+        this.ensureLoaded();
+        return Array.from(this.files.keys());
+    }
+    hasFile(filePath) {
+        this.ensureLoaded();
+        const normalizedPath = normalizePath(filePath);
+        return this.files.has(normalizedPath);
+    }
+    getFilesByPattern(pattern) {
+        this.ensureLoaded();
+        const regexPattern = pattern.replace(/\*/g, '.*').replace(/\?/g, '.');
+        const regex = new RegExp(`^${regexPattern}$`);
+        const matchingFiles = [];
+        for (const [path, file] of this.files) {
+            if (regex.test(path)) {
+                matchingFiles.push(file);
+            }
+        }
+        return matchingFiles;
+    }
+    ensureLoaded() {
+        if (!this.loaded) {
+            throw new Error('Archive not loaded. Call loadFromFile() or loadFromBuffer() first.');
+        }
+    }
+    isLoaded() {
+        return this.loaded;
+    }
+    clear() {
+        this.zip = null;
+        this.files.clear();
+        this.loaded = false;
+    }
+}
+//# sourceMappingURL=ZipReader.js.map

package/dist/esm/zip/ZipReader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ZipReader.js","sourceRoot":"","sources":["../../../src/zip/ZipReader.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,MAAM,OAAO,CAAC;AAC1B,OAAO,EAAE,QAAQ,IAAI,EAAE,EAAE,MAAM,IAAI,CAAC;AAEpC,OAAO,EACL,iBAAiB,EACjB,gBAAgB,EAChB,qBAAqB,EACrB,kBAAkB,GACnB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,qBAAqB,EACrB,YAAY,EACZ,aAAa,EACb,gBAAgB,GACjB,MAAM,wBAAwB,CAAC;AAKhC,MAAM,OAAO,SAAS;IACZ,GAAG,GAAiB,IAAI,CAAC;IACzB,KAAK,GAAY,IAAI,GAAG,EAAE,CAAC;IAC3B,MAAM,GAAG,KAAK,CAAC;IAOvB,KAAK,CAAC,YAAY,CAAC,QAAgB,EAAE,UAAuB,EAAE;QAC5D,IAAI,CAAC;YAEH,IAAI,CAAC;gBACH,MAAM,EAAE,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;YAC5B,CAAC;YAAC,MAAM,CAAC;gBACP,MAAM,IAAI,iBAAiB,CAAC,QAAQ,CAAC,CAAC;YACxC,CAAC;YAGD,MAAM,MAAM,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;YAC3C,MAAM,IAAI,CAAC,cAAc,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAC7C,CAAC;QAAC,OAAO,KAAc,EAAE,CAAC;YACxB,IAAI,KAAK,YAAY,iBAAiB,EAAE,CAAC;gBACvC,MAAM,KAAK,CAAC;YACd,CAAC;YACD,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YACvE,MAAM,IAAI,kBAAkB,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAChD,CAAC;IACH,CAAC;IAOD,KAAK,CAAC,cAAc,CAAC,MAAc,EAAE,UAAuB,EAAE;QAC5D,MAAM,EAAE,QAAQ,GAAG,IAAI,EAAE,GAAG,OAAO,CAAC;QAEpC,IAAI,CAAC;YAEH,IAAI,CAAC,gBAAgB,CAAC,MAAM,CAAC,EAAE,CAAC;gBAC9B,MAAM,IAAI,gBAAgB,CAAC,iCAAiC,CAAC,CAAC;YAChE,CAAC;YAGD,IAAI,CAAC,GAAG,GAAG,MAAM,KAAK,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;YAGzC,MAAM,IAAI,CAAC,YAAY,EAAE,CAAC;YAG1B,IAAI,QAAQ,EAAE,CAAC;gBACb,IAAI,CAAC,QAAQ,EAAE,CAAC;YAClB,CAAC;YAED,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC;QACrB,CAAC;QAAC,OAAO,KAAc,EAAE,CAAC;YACxB,IAAI,KAAK,YAAY,gBAAgB,EAAE,CAAC;gBACtC,MAAM,KAAK,CAAC;YACd,CAAC;YACD,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YACvE,MAAM,IAAI,qBAAqB,CAAC,OAAO,CAAC,CAAC;QAC3C,CAAC;IACH,CAAC;IAWO,KAAK,CAAC,YAAY;QACxB,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC;YACd,MAAM,IAAI,KAAK,CAAC,wBAAwB,CAAC,CAAC;QAC5C,CAAC;QAED,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;QAGnB,MAAM,SAAS,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,GAAI,CAAC,KAAK,CAAC,IAAI,CAAE,CAAC,GAAG,CAAC,CAAC;QAG5F,KAAK,MAAM,QAAQ,IAAI,SAAS,EAAE,CAAC;YACjC,MAAM,cAAc,GAAG,aAAa,CAAC,QAAQ,CAAC,CAAC;YAC/C,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;YAE3C,IAAI,CAAC,SAAS,EAAE,CAAC;gBACf,SAAS;YACX,CAAC;YAED,MAAM,QAAQ,GAAG,YAAY,CAAC,cAAc,CAAC,CAAC;YAK9C,IAAI,OAAO,CAAC;YACZ,IAAI,QAAQ,EAAE,CAAC;gBACb,OAAO,GAAG,MAAM,SAAS,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC;YAChD,CAAC;iBAAM,CAAC;gBAGN,OAAO,GAAG,MAAM,SAAS,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;YAC5C,CAAC;YAGD,MAAM,IAAI,GAAG,SAAS,CAAC,IAAI,CAAC;YAG5B,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,cAAc,EAAE;gBAC7B,IAAI,EAAE,cAAc;gBACpB,OAAO;gBACP,QAAQ;gBACR,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAE,OAAkB,CAAC,MAAM,CAAC,CAAC,CAAE,OAAkB,CAAC,MAAM;gBACxE,IAAI;aACL,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAMO,QAAQ;QACd,MAAM,SAAS,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC;QAChD,qBAAqB,CAAC,SAAS,CAAC,CAAC;IACnC,CAAC;IAOD,OAAO,CAAC,QAAgB;QACtB,IAAI,CAAC,YAAY,EAAE,CAAC;QACpB,MAAM,cAAc,GAAG,aAAa,CAAC,QAAQ,CAAC,CAAC;QAC/C,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IACxC,CAAC;IAYD,eAAe,CAAC,QAAgB;QAC9B,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;QACpC,IAAI,CAAC,IAAI,EAAE,CAAC;YACV,OAAO,SAAS,CAAC;QACnB,CAAC;QAID,IAAI,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;YAElC,OAAO,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;QACvC,CAAC;QAED,OAAO,IAAI,CAAC,OAAO,CAAC;IACtB,CAAC;IAYD,eAAe,CAAC,QAAgB;QAC9B,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;QACpC,IAAI,CAAC,IAAI,EAAE,CAAC;YACV,OAAO,SAAS,CAAC;QACnB,CAAC;QAID,IAAI,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;YAClC,OAAO,IAAI,CAAC,OAAO,CAAC;QACtB,CAAC;QAGD,OAAO,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IAC3C,CAAC;IAMD,WAAW;QACT,IAAI,CAAC,YAAY,EAAE,CAAC;QACpB,OAAO,IAAI,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAC7B,CAAC;IAMD,YAAY;QACV,IAAI,CAAC,YAAY,EAAE,CAAC;QACpB,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC;IACvC,CAAC;IAOD,OAAO,CAAC,QAAgB;QACtB,IAAI,CAAC,YAAY,EAAE,CAAC;QACpB,MAAM,cAAc,GAAG,aAAa,CAAC,QAAQ,CAAC,CAAC;QAC/C,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IACxC,CAAC;IAOD,iBAAiB,CAAC,OAAe;QAC/B,IAAI,CAAC,YAAY,EAAE,CAAC;QAGpB,MAAM,YAAY,GAAG,OAAO,CAAC,OAAO,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;QACtE,MAAM,KAAK,GAAG,IAAI,MAAM,CAAC,IAAI,YAAY,GAAG,CAAC,CAAC;QAE9C,MAAM,aAAa,GAAc,EAAE,CAAC;QACpC,KAAK,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;YACtC,IAAI,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;gBACrB,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YAC3B,CAAC;QACH,CAAC;QAED,OAAO,aAAa,CAAC;IACvB,CAAC;IAMO,YAAY;QAClB,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC;YACjB,MAAM,IAAI,KAAK,CAAC,oEAAoE,CAAC,CAAC;QACxF,CAAC;IACH,CAAC;IAMD,QAAQ;QACN,OAAO,IAAI,CAAC,MAAM,CAAC;IACrB,CAAC;IAKD,KAAK;QACH,IAAI,CAAC,GAAG,GAAG,IAAI,CAAC;QAChB,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;QACnB,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC;IACtB,CAAC;CACF","sourcesContent":["/**\n * ZipReader - Handles reading ZIP archives (DOCX files)\n */\n\nimport JSZip from 'jszip';\nimport { promises as fs } from 'fs';\nimport { ZipFile, FileMap, LoadOptions } from './types.js';\nimport {\n  DocxNotFoundError,\n  InvalidDocxError,\n  CorruptedArchiveError,\n  FileOperationError,\n} from './errors.js';\nimport {\n  validateDocxStructure,\n  isBinaryFile,\n  normalizePath,\n  isValidZipBuffer,\n} from '../utils/validation.js';\n\n/**\n * Handles reading operations on ZIP archives\n */\nexport class ZipReader {\n  private zip: JSZip | null = null;\n  private files: FileMap = new Map();\n  private loaded = false;\n\n  /**\n   * Loads a DOCX file from the filesystem\n   * @param filePath - Path to the DOCX file\n   * @param options - Load options\n   */\n  async loadFromFile(filePath: string, options: LoadOptions = {}): Promise<void> {\n    try {\n      // Check if file exists\n      try {\n        await fs.access(filePath);\n      } catch {\n        throw new DocxNotFoundError(filePath);\n      }\n\n      // Read file as buffer\n      const buffer = await fs.readFile(filePath);\n      await this.loadFromBuffer(buffer, options);\n    } catch (error: unknown) {\n      if (error instanceof DocxNotFoundError) {\n        throw error;\n      }\n      const message = error instanceof Error ? error.message : String(error);\n      throw new FileOperationError('read', message);\n    }\n  }\n\n  /**\n   * Loads a DOCX file from a buffer\n   * @param buffer - Buffer containing the DOCX data\n   * @param options - Load options\n   */\n  async loadFromBuffer(buffer: Buffer, options: LoadOptions = {}): Promise<void> {\n    const { validate = true } = options;\n\n    try {\n      // Validate ZIP signature\n      if (!isValidZipBuffer(buffer)) {\n        throw new InvalidDocxError('File is not a valid ZIP archive');\n      }\n\n      // Load ZIP archive\n      this.zip = await JSZip.loadAsync(buffer);\n\n      // Extract all files\n      await this.extractFiles();\n\n      // Validate DOCX structure if requested\n      if (validate) {\n        this.validate();\n      }\n\n      this.loaded = true;\n    } catch (error: unknown) {\n      if (error instanceof InvalidDocxError) {\n        throw error;\n      }\n      const message = error instanceof Error ? error.message : String(error);\n      throw new CorruptedArchiveError(message);\n    }\n  }\n\n  /**\n   * Extracts all files from the ZIP archive into memory\n   *\n   * **Encoding Note:**\n   * - Text files (XML, etc.) are extracted as UTF-8 strings using `async('string')`\n   * - JSZip automatically decodes UTF-8 when extracting as 'string'\n   * - Binary files are extracted as Buffers to preserve exact content\n   * - All text content is guaranteed to be valid UTF-8\n   */\n  private async extractFiles(): Promise<void> {\n    if (!this.zip) {\n      throw new Error('ZIP archive not loaded');\n    }\n\n    this.files.clear();\n\n    // Get all file paths\n    const filePaths = Object.keys(this.zip.files).filter((path) => !this.zip!.files[path]!.dir);\n\n    // Extract each file\n    for (const filePath of filePaths) {\n      const normalizedPath = normalizePath(filePath);\n      const zipObject = this.zip.files[filePath];\n\n      if (!zipObject) {\n        continue;\n      }\n\n      const isBinary = isBinaryFile(normalizedPath);\n\n      // Extract content based on type\n      // For text files: JSZip's async('string') automatically uses UTF-8 decoding\n      // For binary files: async('nodebuffer') preserves exact bytes\n      let content;\n      if (isBinary) {\n        content = await zipObject.async('nodebuffer');\n      } else {\n        // Text files are extracted as UTF-8 strings\n        // JSZip automatically handles UTF-8 decoding for 'string' type\n        content = await zipObject.async('string');\n      }\n\n      // Get file metadata\n      const date = zipObject.date;\n\n      // Store file information\n      this.files.set(normalizedPath, {\n        path: normalizedPath,\n        content,\n        isBinary,\n        size: isBinary ? (content as Buffer).length : (content as string).length,\n        date,\n      });\n    }\n  }\n\n  /**\n   * Validates the DOCX structure\n   * @throws {MissingRequiredFileError} If required files are missing\n   */\n  private validate(): void {\n    const filePaths = Array.from(this.files.keys());\n    validateDocxStructure(filePaths);\n  }\n\n  /**\n   * Gets a specific file from the archive\n   * @param filePath - Path to the file within the archive\n   * @returns The file data, or undefined if not found\n   */\n  getFile(filePath: string): ZipFile | undefined {\n    this.ensureLoaded();\n    const normalizedPath = normalizePath(filePath);\n    return this.files.get(normalizedPath);\n  }\n\n  /**\n   * Gets the content of a specific file as a string\n   * @param filePath - Path to the file within the archive\n   * @returns The file content as a UTF-8 string, or undefined if not found\n   *\n   * **Encoding Note:**\n   * - Returns UTF-8 decoded string content\n   * - For binary files, converts the Buffer to UTF-8 string\n   * - Assumes all text content is UTF-8 encoded (per OpenXML standard)\n   */\n  getFileAsString(filePath: string): string | undefined {\n    const file = this.getFile(filePath);\n    if (!file) {\n      return undefined;\n    }\n\n    // Check actual content type instead of flag (Issue #4)\n    // Content is Buffer for binary files, string for text files\n    if (Buffer.isBuffer(file.content)) {\n      // Convert binary buffer to UTF-8 string\n      return file.content.toString('utf8');\n    }\n\n    return file.content;\n  }\n\n  /**\n   * Gets the content of a specific file as a buffer\n   * @param filePath - Path to the file within the archive\n   * @returns The file content as a Buffer, or undefined if not found\n   *\n   * **Encoding Note:**\n   * - Returns Buffer with UTF-8 encoded content for text files\n   * - For binary files, returns raw bytes\n   * - String content is explicitly encoded as UTF-8\n   */\n  getFileAsBuffer(filePath: string): Buffer | undefined {\n    const file = this.getFile(filePath);\n    if (!file) {\n      return undefined;\n    }\n\n    // Check actual content type instead of flag (Issue #4)\n    // Content is Buffer for binary files, string for text files\n    if (Buffer.isBuffer(file.content)) {\n      return file.content;\n    }\n\n    // Encode string content as UTF-8 Buffer\n    return Buffer.from(file.content, 'utf8');\n  }\n\n  /**\n   * Gets all files from the archive\n   * @returns Map of file paths to file data\n   */\n  getAllFiles(): FileMap {\n    this.ensureLoaded();\n    return new Map(this.files);\n  }\n\n  /**\n   * Gets a list of all file paths in the archive\n   * @returns Array of file paths\n   */\n  getFilePaths(): string[] {\n    this.ensureLoaded();\n    return Array.from(this.files.keys());\n  }\n\n  /**\n   * Checks if a file exists in the archive\n   * @param filePath - Path to check\n   * @returns True if the file exists\n   */\n  hasFile(filePath: string): boolean {\n    this.ensureLoaded();\n    const normalizedPath = normalizePath(filePath);\n    return this.files.has(normalizedPath);\n  }\n\n  /**\n   * Gets files matching a pattern (simple glob)\n   * @param pattern - Pattern to match (supports * wildcard)\n   * @returns Array of matching files\n   */\n  getFilesByPattern(pattern: string): ZipFile[] {\n    this.ensureLoaded();\n\n    // Convert simple glob pattern to regex\n    const regexPattern = pattern.replace(/\\*/g, '.*').replace(/\\?/g, '.');\n    const regex = new RegExp(`^${regexPattern}$`);\n\n    const matchingFiles: ZipFile[] = [];\n    for (const [path, file] of this.files) {\n      if (regex.test(path)) {\n        matchingFiles.push(file);\n      }\n    }\n\n    return matchingFiles;\n  }\n\n  /**\n   * Ensures the archive is loaded before operations\n   * @throws {Error} If archive is not loaded\n   */\n  private ensureLoaded(): void {\n    if (!this.loaded) {\n      throw new Error('Archive not loaded. Call loadFromFile() or loadFromBuffer() first.');\n    }\n  }\n\n  /**\n   * Checks if the archive is loaded\n   * @returns True if loaded\n   */\n  isLoaded(): boolean {\n    return this.loaded;\n  }\n\n  /**\n   * Clears all loaded data\n   */\n  clear(): void {\n    this.zip = null;\n    this.files.clear();\n    this.loaded = false;\n  }\n}\n"]}