@fgv/ts-res 5.0.0-16 → 5.0.0-18

package/src/packlets/zip-archive/types.ts

@@ -0,0 +1,140 @@
+/*
+ * Copyright (c) 2025 Erik Fortune
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+import { Model as ConfigModel } from '../config';
+import * as Json from './json';
+import { FileTree } from '@fgv/ts-utils';
+
+/**
+ * Options for creating a ZIP archive buffer
+ * @public
+ */
+export interface IZipArchivePathOptions {
+  /** File or directory path to include in the archive */
+  inputPath?: string;
+  /** Optional configuration file path */
+  configPath?: string;
+}
+
+/**
+ * Options for creating a ZIP archive buffer from a file tree
+ * @public
+ */
+export interface IZipArchiveFileTreeOptions {
+  /** Input file or directory */
+  inputItem?: FileTree.FileTreeItem;
+  /** Optional configuration file */
+  configItem?: FileTree.IFileTreeFileItem;
+}
+
+/**
+ * Options for creating a ZIP archive buffer
+ * @public
+ */
+export type ZipArchiveOptions = IZipArchivePathOptions | IZipArchiveFileTreeOptions;
+
+/**
+ * Standardized ZIP archive manifest format (compatible with existing tools)
+ * @public
+ */
+export type IZipArchiveManifest = Json.IZipArchiveManifest;
+
+/**
+ * Result of ZIP archive buffer creation
+ * @public
+ */
+export interface IZipArchiveResult {
+  /** Raw ZIP data buffer */
+  zipBuffer: Uint8Array;
+  /** Archive manifest with metadata */
+  manifest: IZipArchiveManifest;
+  /** Total ZIP size in bytes */
+  size: number;
+}
+
+/**
+ * Options for loading a ZIP archive
+ * @public
+ */
+export interface IZipArchiveLoadOptions {
+  /** Validate manifest strictly */
+  strictManifestValidation?: boolean;
+}
+
+/**
+ * Result of ZIP archive loading
+ * @public
+ */
+export interface IZipArchiveLoadResult {
+  /** Parsed archive manifest */
+  manifest: IZipArchiveManifest | undefined;
+  /** Loaded configuration */
+  config: ConfigModel.ISystemConfiguration | undefined;
+  /** All files extracted from the archive */
+  files: IImportedFile[];
+  /** Directory structure if available */
+  directory: IImportedDirectory | undefined;
+}
+
+/**
+ * Imported file representation
+ * @public
+ */
+export type IImportedFile = Json.IImportedFile;
+
+/**
+ * Imported directory structure
+ * @public
+ */
+export type IImportedDirectory = Json.IImportedDirectory;
+
+/**
+ * Progress callback for ZIP operations
+ * @public
+ */
+export type ZipArchiveProgressCallback = (
+  stage:
+    | 'reading-file'
+    | 'parsing-zip'
+    | 'loading-manifest'
+    | 'loading-config'
+    | 'extracting-files'
+    | 'processing-resources'
+    | 'creating-zip',
+  progress: number, // 0-100
+  details: string
+) => void;
+
+/**
+ * Constants for ZIP archive structure
+ * @public
+ */
+export const ZipArchiveConstants = {
+  /** Manifest file name */
+  MANIFEST_FILE: 'manifest.json',
+  /** Configuration file name */
+  CONFIG_FILE: 'config.json',
+  /** Input files directory */
+  INPUT_DIR: 'input',
+  /** Configuration files directory */
+  CONFIG_DIR: 'config'
+} as const;

package/src/packlets/zip-archive/zipArchiveCreator.ts

@@ -0,0 +1,229 @@
+/*
+ * Copyright (c) 2025 Erik Fortune
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+import { zipSync } from 'fflate';
+import { Result, succeed, fail, FileTree } from '@fgv/ts-utils';
+import type { IZipArchiveResult, ZipArchiveOptions, ZipArchiveProgressCallback } from './types';
+import { normalizePath } from './zipArchiveFormat';
+import * as Json from './json';
+
+/**
+ * ZIP archive creator using fflate for universal compatibility
+ * @public
+ */
+export class ZipArchiveCreator {
+  /**
+   * Create a ZIP archive buffer from a supplied buffer
+   * @param options - Input paths and configuration
+   * @param onProgress - Optional progress callback
+   * @returns Result containing ZIP buffer and manifest
+   */
+  public async createFromBuffer(
+    options: ZipArchiveOptions,
+    onProgress?: ZipArchiveProgressCallback
+  ): Promise<Result<IZipArchiveResult>> {
+    try {
+      onProgress?.('creating-zip', 0, 'Starting ZIP archive creation');
+
+      const files: Record<string, Uint8Array> = {};
+      const manifest: Json.IZipArchiveManifest = {
+        timestamp: new Date().toISOString()
+      };
+
+      const { value: inputItem, message: inputItemError } = this._getInputFileTreeItem(options);
+      if (inputItemError !== undefined) {
+        return fail(inputItemError);
+      }
+
+      if (inputItem !== undefined) {
+        onProgress?.('reading-file', 10, `Processing input: ${inputItem.absolutePath}`);
+
+        if (inputItem.type === 'directory') {
+          // Add entire directory recursively, preserving structure
+          const archivePath = `input/${inputItem.name}`;
+
+          const addDirResult = await this._addDirectoryTreeToZip(files, inputItem, archivePath, onProgress);
+          /* c8 ignore next 3 - defense in depth against internal error */
+          if (addDirResult.isFailure()) {
+            return fail(addDirResult.message);
+          }
+
+          manifest.input = {
+            type: 'directory',
+            originalPath: inputItem.absolutePath,
+            archivePath
+          };
+        } else if (inputItem.type === 'file') {
+          // Add single file
+          const archivePath = `input/${inputItem.name}`;
+
+          const addFileResult = await this._addFileTreeItemToZip(files, inputItem, archivePath);
+          /* c8 ignore next 3 - defense in depth against internal error */
+          if (addFileResult.isFailure()) {
+            return fail(addFileResult.message);
+          }
+
+          manifest.input = {
+            type: 'file',
+            originalPath: inputItem.absolutePath,
+            archivePath
+          };
+        }
+      }
+
+      const { value: configItem, message: configItemError } = this._getConfigFileTreeItem(options);
+      if (configItemError !== undefined) {
+        return fail(configItemError);
+      }
+
+      if (configItem !== undefined) {
+        onProgress?.('reading-file', 40, `Processing config: ${configItem.absolutePath}`);
+
+        const archivePath = `config/${configItem.name}`;
+
+        const addConfigResult = await this._addFileTreeItemToZip(files, configItem, archivePath);
+        /* c8 ignore next 3 - defense in depth against internal error */
+        if (addConfigResult.isFailure()) {
+          return fail(addConfigResult.message);
+        }
+
+        // Update manifest with config info
+        manifest.config = {
+          type: 'file',
+          originalPath: configItem.absolutePath,
+          archivePath
+        };
+      }
+
+      // Add manifest to ZIP
+      onProgress?.('creating-zip', 70, 'Adding manifest');
+      const manifestJson = JSON.stringify(manifest, null, 2);
+      files['manifest.json'] = new TextEncoder().encode(manifestJson);
+
+      // Create ZIP buffer using fflate
+      onProgress?.('creating-zip', 80, 'Compressing files');
+      const zipBuffer = zipSync(files, { level: 6 });
+
+      const result: IZipArchiveResult = {
+        zipBuffer,
+        manifest,
+        size: zipBuffer.length
+      };
+
+      onProgress?.('creating-zip', 100, 'ZIP archive buffer created');
+
+      return succeed(result);
+      /* c8 ignore next 3 - defense in depth against internal error */
+    } catch (error) {
+      return fail(`Failed to create ZIP archive: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+
+  /**
+   * Add a single FileTree item to the ZIP archive
+   * @param files - ZIP files collection
+   * @param fileItem - FileTree file item to add
+   * @param archivePath - Path within the archive
+   * @returns Result indicating success or failure
+   */
+  private async _addFileTreeItemToZip(
+    files: Record<string, Uint8Array>,
+    fileItem: FileTree.IFileTreeFileItem,
+    archivePath: string
+  ): Promise<Result<void>> {
+    return fileItem.getRawContents().onSuccess((content) => {
+      const contentBuffer = new TextEncoder().encode(content);
+      files[normalizePath(archivePath)] = contentBuffer;
+      return succeed(undefined);
+    });
+  }
+
+  /**
+   * Add a directory recursively to the ZIP archive using FileTree
+   * @param files - ZIP files collection
+   * @param directoryItem - FileTree directory item to add
+   * @param archivePrefix - Prefix path within the archive
+   * @param onProgress - Optional progress callback
+   * @returns Result indicating success or failure
+   */
+  private async _addDirectoryTreeToZip(
+    files: Record<string, Uint8Array>,
+    directoryItem: FileTree.IFileTreeDirectoryItem,
+    archivePrefix: string,
+    onProgress?: ZipArchiveProgressCallback
+  ): Promise<Result<void>> {
+    const childrenResult = directoryItem.getChildren();
+    /* c8 ignore next 3 - defense in depth against internal error */
+    if (childrenResult.isFailure()) {
+      return fail(`Failed to read directory ${directoryItem.absolutePath}: ${childrenResult.message}`);
+    }
+
+    for (const child of childrenResult.value) {
+      const itemArchivePath = normalizePath(`${archivePrefix}/${child.name}`);
+
+      if (child.type === 'directory') {
+        // Recursively add subdirectory
+        const addDirResult = await this._addDirectoryTreeToZip(files, child, itemArchivePath, onProgress);
+        /* c8 ignore next 3 - defense in depth against internal error */
+        if (addDirResult.isFailure()) {
+          return fail(addDirResult.message);
+        }
+      } else if (child.type === 'file') {
+        // Add file
+        const addFileResult = await this._addFileTreeItemToZip(files, child, itemArchivePath);
+        /* c8 ignore next 3 - defense in depth against internal error */
+        if (addFileResult.isFailure()) {
+          return fail(addFileResult.message);
+        }
+        onProgress?.('reading-file', 0, `Added file: ${itemArchivePath}`);
+      }
+    }
+
+    return succeed(undefined);
+  }
+
+  private _getInputFileTreeItem(options: ZipArchiveOptions): Result<FileTree.FileTreeItem | undefined> {
+    if ('inputPath' in options && options.inputPath !== undefined) {
+      return FileTree.forFilesystem()
+        .withErrorFormat((msg) => `Failed to create file tree: ${msg}`)
+        .onSuccess((fileTree) =>
+          fileTree.getItem(options.inputPath!).withErrorFormat((msg) => `Failed to get item: ${msg}`)
+        );
+    } else if ('inputItem' in options) {
+      return succeed(options.inputItem);
+    }
+    return succeed(undefined);
+  }
+
+  private _getConfigFileTreeItem(options: ZipArchiveOptions): Result<FileTree.IFileTreeFileItem | undefined> {
+    if ('configPath' in options && options.configPath !== undefined) {
+      return FileTree.forFilesystem()
+        .withErrorFormat((msg) => `Failed to create file tree: ${msg}`)
+        .onSuccess((fileTree) =>
+          fileTree.getFile(options.configPath!).withErrorFormat((msg) => `Failed to get config file: ${msg}`)
+        );
+    } else if ('configItem' in options && options.configItem !== undefined) {
+      return succeed(options.configItem);
+    }
+    return succeed(undefined);
+  }
+}

package/src/packlets/zip-archive/zipArchiveFormat.ts

@@ -0,0 +1,158 @@
+/*
+ * Copyright (c) 2025 Erik Fortune
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+import { Result, captureResult } from '@fgv/ts-utils';
+import { Model as ConfigModel } from '../config';
+import * as Json from './json';
+import * as Convert from './convert';
+
+/**
+ * Create a ZIP archive manifest object
+ * @param inputType - Type of input (file or directory)
+ * @param originalPath - Original file/directory path
+ * @param archivePath - Path within the archive
+ * @param configPath - Optional configuration file path
+ * @returns ZIP archive manifest
+ * @public
+ */
+export function createZipArchiveManifest(
+  inputType: 'file' | 'directory',
+  originalPath: string,
+  archivePath: string,
+  configPath?: string
+): Json.IZipArchiveManifest {
+  const manifest: Json.IZipArchiveManifest = {
+    timestamp: new Date().toISOString(),
+    input: {
+      type: inputType,
+      originalPath,
+      archivePath
+    }
+  };
+
+  if (configPath) {
+    manifest.config = {
+      type: 'file',
+      originalPath: configPath,
+      archivePath: 'config.json'
+    };
+  }
+
+  return manifest;
+}
+
+/**
+ * Parse and validate a ZIP archive manifest
+ * @param manifestData - JSON string containing manifest data
+ * @returns Result containing validated manifest
+ * @public
+ */
+export function parseZipArchiveManifest(manifestData: string): Result<Json.IZipArchiveManifest> {
+  return captureResult(() => {
+    const parsed = JSON.parse(manifestData);
+    return parsed;
+  })
+    .onSuccess((parsed) => Convert.zipArchiveManifest.validate(parsed))
+    .withErrorFormat((e) => `Failed to parse ZIP archive manifest: ${e}`);
+}
+
+/**
+ * Validate a ZIP archive manifest object
+ * @param manifest - Object to validate as manifest
+ * @returns Result containing validated manifest
+ * @public
+ */
+export function validateZipArchiveManifest(manifest: unknown): Result<Json.IZipArchiveManifest> {
+  return Convert.zipArchiveManifest.validate(manifest);
+}
+
+/**
+ * Parse and validate configuration JSON
+ * @param configData - JSON string containing configuration
+ * @returns Result containing validated configuration
+ * @public
+ */
+export function parseZipArchiveConfiguration(configData: string): Result<ConfigModel.ISystemConfiguration> {
+  return captureResult(() => {
+    const parsed = JSON.parse(configData);
+    return parsed;
+  })
+    .onSuccess((parsed) => Convert.systemConfiguration.validate(parsed))
+    .withErrorFormat((e) => `Failed to parse ZIP archive configuration: ${e}`);
+}
+
+/**
+ * Generate a timestamp-based filename for ZIP archives
+ * @param customName - Optional custom name prefix
+ * @returns Generated filename
+ * @public
+ */
+export function generateZipArchiveFilename(customName?: string): string {
+  const timestamp = new Date().toISOString().replace(/[:.]/g, '-').replace('T', '_').slice(0, -5);
+  return customName ? `${customName}-${timestamp}.zip` : `ts-res-archive-${timestamp}.zip`;
+}
+
+/**
+ * Normalize path separators for cross-platform compatibility
+ * @param path - Path to normalize
+ * @returns Normalized path
+ * @public
+ */
+export function normalizePath(path: string): string {
+  return path.replace(/\\/g, '/').replace(/\/+/g, '/');
+}
+
+/**
+ * Extract directory name from a file path
+ * @param path - File path
+ * @returns Directory name
+ * @public
+ */
+export function getDirectoryName(path: string): string {
+  const normalized = normalizePath(path);
+  const parts = normalized.split('/');
+  return parts[parts.length - 1] || 'archive';
+}
+
+/**
+ * Create a safe filename by removing invalid characters
+ * @param filename - Original filename
+ * @returns Sanitized filename
+ * @public
+ */
+export function sanitizeFilename(filename: string): string {
+  return filename
+    .replace(/[<>:"/\\|?*]/g, '_')
+    .replace(/\s+/g, '_')
+    .replace(/_+/g, '_')
+    .trim();
+}
+
+/**
+ * Validate ZIP file extension
+ * @param filename - Filename to validate
+ * @returns True if filename has .zip extension
+ * @public
+ */
+export function isZipFile(filename: string): boolean {
+  return filename.toLowerCase().endsWith('.zip');
+}