@fgv/ts-res 5.0.0-3 → 5.0.0-31

package/lib/packlets/zip-archive/types.d.ts

@@ -0,0 +1,98 @@
+import { Model as ConfigModel } from '../config';
+import * as Json from './json';
+import { FileTree } from '@fgv/ts-json-base';
+/**
+ * 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 declare const ZipArchiveConstants: {
+    /** Manifest file name */
+    readonly MANIFEST_FILE: "manifest.json";
+    /** Configuration file name */
+    readonly CONFIG_FILE: "config.json";
+    /** Input files directory */
+    readonly INPUT_DIR: "input";
+    /** Configuration files directory */
+    readonly CONFIG_DIR: "config";
+};
+//# sourceMappingURL=types.d.ts.map

package/lib/packlets/zip-archive/types.js

@@ -0,0 +1,39 @@
+"use strict";
+/*
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZipArchiveConstants = void 0;
+/**
+ * Constants for ZIP archive structure
+ * @public
+ */
+exports.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'
+};
+//# sourceMappingURL=types.js.map

package/lib/packlets/zip-archive/zipArchiveCreator.d.ts

@@ -0,0 +1,35 @@
+import { Result } from '@fgv/ts-utils';
+import type { IZipArchiveResult, ZipArchiveOptions, ZipArchiveProgressCallback } from './types';
+/**
+ * ZIP archive creator using fflate for universal compatibility
+ * @public
+ */
+export declare 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
+     */
+    createFromBuffer(options: ZipArchiveOptions, onProgress?: ZipArchiveProgressCallback): Promise<Result<IZipArchiveResult>>;
+    /**
+     * 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 _addFileTreeItemToZip;
+    /**
+     * 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 _addDirectoryTreeToZip;
+    private _getInputFileTreeItem;
+    private _getConfigFileTreeItem;
+}
+//# sourceMappingURL=zipArchiveCreator.d.ts.map

package/lib/packlets/zip-archive/zipArchiveCreator.js

@@ -0,0 +1,195 @@
+"use strict";
+/*
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZipArchiveCreator = void 0;
+const fflate_1 = require("fflate");
+const ts_utils_1 = require("@fgv/ts-utils");
+const ts_json_base_1 = require("@fgv/ts-json-base");
+const zipArchiveFormat_1 = require("./zipArchiveFormat");
+/**
+ * ZIP archive creator using fflate for universal compatibility
+ * @public
+ */
+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
+     */
+    async createFromBuffer(options, onProgress) {
+        try {
+            onProgress === null || onProgress === void 0 ? void 0 : onProgress('creating-zip', 0, 'Starting ZIP archive creation');
+            const files = {};
+            const manifest = {
+                timestamp: new Date().toISOString()
+            };
+            const { value: inputItem, message: inputItemError } = this._getInputFileTreeItem(options);
+            if (inputItemError !== undefined) {
+                return (0, ts_utils_1.fail)(inputItemError);
+            }
+            if (inputItem !== undefined) {
+                onProgress === null || onProgress === void 0 ? void 0 : 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 (0, ts_utils_1.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 (0, ts_utils_1.fail)(addFileResult.message);
+                    }
+                    manifest.input = {
+                        type: 'file',
+                        originalPath: inputItem.absolutePath,
+                        archivePath
+                    };
+                }
+            }
+            const { value: configItem, message: configItemError } = this._getConfigFileTreeItem(options);
+            if (configItemError !== undefined) {
+                return (0, ts_utils_1.fail)(configItemError);
+            }
+            if (configItem !== undefined) {
+                onProgress === null || onProgress === void 0 ? void 0 : 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 (0, ts_utils_1.fail)(addConfigResult.message);
+                }
+                // Update manifest with config info
+                manifest.config = {
+                    type: 'file',
+                    originalPath: configItem.absolutePath,
+                    archivePath
+                };
+            }
+            // Add manifest to ZIP
+            onProgress === null || onProgress === void 0 ? void 0 : 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 === null || onProgress === void 0 ? void 0 : onProgress('creating-zip', 80, 'Compressing files');
+            const zipBuffer = (0, fflate_1.zipSync)(files, { level: 6 });
+            const result = {
+                zipBuffer,
+                manifest,
+                size: zipBuffer.length
+            };
+            onProgress === null || onProgress === void 0 ? void 0 : onProgress('creating-zip', 100, 'ZIP archive buffer created');
+            return (0, ts_utils_1.succeed)(result);
+            /* c8 ignore next 3 - defense in depth against internal error */
+        }
+        catch (error) {
+            return (0, ts_utils_1.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
+     */
+    async _addFileTreeItemToZip(files, fileItem, archivePath) {
+        return fileItem.getRawContents().onSuccess((content) => {
+            const contentBuffer = new TextEncoder().encode(content);
+            files[(0, zipArchiveFormat_1.normalizePath)(archivePath)] = contentBuffer;
+            return (0, ts_utils_1.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
+     */
+    async _addDirectoryTreeToZip(files, directoryItem, archivePrefix, onProgress) {
+        const childrenResult = directoryItem.getChildren();
+        /* c8 ignore next 3 - defense in depth against internal error */
+        if (childrenResult.isFailure()) {
+            return (0, ts_utils_1.fail)(`Failed to read directory ${directoryItem.absolutePath}: ${childrenResult.message}`);
+        }
+        for (const child of childrenResult.value) {
+            const itemArchivePath = (0, zipArchiveFormat_1.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 (0, ts_utils_1.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 (0, ts_utils_1.fail)(addFileResult.message);
+                }
+                onProgress === null || onProgress === void 0 ? void 0 : onProgress('reading-file', 0, `Added file: ${itemArchivePath}`);
+            }
+        }
+        return (0, ts_utils_1.succeed)(undefined);
+    }
+    _getInputFileTreeItem(options) {
+        if ('inputPath' in options && options.inputPath !== undefined) {
+            return ts_json_base_1.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 (0, ts_utils_1.succeed)(options.inputItem);
+        }
+        return (0, ts_utils_1.succeed)(undefined);
+    }
+    _getConfigFileTreeItem(options) {
+        if ('configPath' in options && options.configPath !== undefined) {
+            return ts_json_base_1.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 (0, ts_utils_1.succeed)(options.configItem);
+        }
+        return (0, ts_utils_1.succeed)(undefined);
+    }
+}
+exports.ZipArchiveCreator = ZipArchiveCreator;
+//# sourceMappingURL=zipArchiveCreator.js.map

package/lib/packlets/zip-archive/zipArchiveFormat.d.ts

@@ -0,0 +1,70 @@
+import { Result } from '@fgv/ts-utils';
+import { Model as ConfigModel } from '../config';
+import * as Json from './json';
+/**
+ * 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 declare function createZipArchiveManifest(inputType: 'file' | 'directory', originalPath: string, archivePath: string, configPath?: string): Json.IZipArchiveManifest;
+/**
+ * Parse and validate a ZIP archive manifest
+ * @param manifestData - JSON string containing manifest data
+ * @returns Result containing validated manifest
+ * @public
+ */
+export declare function parseZipArchiveManifest(manifestData: string): Result<Json.IZipArchiveManifest>;
+/**
+ * Validate a ZIP archive manifest object
+ * @param manifest - Object to validate as manifest
+ * @returns Result containing validated manifest
+ * @public
+ */
+export declare function validateZipArchiveManifest(manifest: unknown): Result<Json.IZipArchiveManifest>;
+/**
+ * Parse and validate configuration JSON
+ * @param configData - JSON string containing configuration
+ * @returns Result containing validated configuration
+ * @public
+ */
+export declare function parseZipArchiveConfiguration(configData: string): Result<ConfigModel.ISystemConfiguration>;
+/**
+ * Generate a timestamp-based filename for ZIP archives
+ * @param customName - Optional custom name prefix
+ * @returns Generated filename
+ * @public
+ */
+export declare function generateZipArchiveFilename(customName?: string): string;
+/**
+ * Normalize path separators for cross-platform compatibility
+ * @param path - Path to normalize
+ * @returns Normalized path
+ * @public
+ */
+export declare function normalizePath(path: string): string;
+/**
+ * Extract directory name from a file path
+ * @param path - File path
+ * @returns Directory name
+ * @public
+ */
+export declare function getDirectoryName(path: string): string;
+/**
+ * Create a safe filename by removing invalid characters
+ * @param filename - Original filename
+ * @returns Sanitized filename
+ * @public
+ */
+export declare function sanitizeFilename(filename: string): string;
+/**
+ * Validate ZIP file extension
+ * @param filename - Filename to validate
+ * @returns True if filename has .zip extension
+ * @public
+ */
+export declare function isZipFile(filename: string): boolean;
+//# sourceMappingURL=zipArchiveFormat.d.ts.map

package/lib/packlets/zip-archive/zipArchiveFormat.js

@@ -0,0 +1,184 @@
+"use strict";
+/*
+ * 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.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createZipArchiveManifest = createZipArchiveManifest;
+exports.parseZipArchiveManifest = parseZipArchiveManifest;
+exports.validateZipArchiveManifest = validateZipArchiveManifest;
+exports.parseZipArchiveConfiguration = parseZipArchiveConfiguration;
+exports.generateZipArchiveFilename = generateZipArchiveFilename;
+exports.normalizePath = normalizePath;
+exports.getDirectoryName = getDirectoryName;
+exports.sanitizeFilename = sanitizeFilename;
+exports.isZipFile = isZipFile;
+const ts_utils_1 = require("@fgv/ts-utils");
+const Convert = __importStar(require("./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
+ */
+function createZipArchiveManifest(inputType, originalPath, archivePath, configPath) {
+    const manifest = {
+        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
+ */
+function parseZipArchiveManifest(manifestData) {
+    return (0, ts_utils_1.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
+ */
+function validateZipArchiveManifest(manifest) {
+    return Convert.zipArchiveManifest.validate(manifest);
+}
+/**
+ * Parse and validate configuration JSON
+ * @param configData - JSON string containing configuration
+ * @returns Result containing validated configuration
+ * @public
+ */
+function parseZipArchiveConfiguration(configData) {
+    return (0, ts_utils_1.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
+ */
+function generateZipArchiveFilename(customName) {
+    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
+ */
+function normalizePath(path) {
+    return path.replace(/\\/g, '/').replace(/\/+/g, '/');
+}
+/**
+ * Extract directory name from a file path
+ * @param path - File path
+ * @returns Directory name
+ * @public
+ */
+function getDirectoryName(path) {
+    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
+ */
+function sanitizeFilename(filename) {
+    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
+ */
+function isZipFile(filename) {
+    return filename.toLowerCase().endsWith('.zip');
+}
+//# sourceMappingURL=zipArchiveFormat.js.map