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

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

@@ -0,0 +1,104 @@
+"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.systemConfiguration = exports.importedDirectory = exports.importedFile = exports.mimeType = exports.zipArchiveManifest = exports.zipArchiveConfigInfo = exports.zipArchiveInputInfo = exports.zipArchiveConfigType = exports.zipArchiveInputType = void 0;
+/* eslint-disable @rushstack/typedef-var */
+const ts_utils_1 = require("@fgv/ts-utils");
+const config_1 = require("../config");
+/**
+ * Validator for ZIP archive input type
+ * @public
+ */
+exports.zipArchiveInputType = ts_utils_1.Validators.enumeratedValue([
+    'file',
+    'directory'
+]);
+/**
+ * Validator for ZIP archive config type
+ * @public
+ */
+exports.zipArchiveConfigType = ts_utils_1.Validators.enumeratedValue(['file']);
+/**
+ * Validator for ZIP archive input information
+ * @public
+ */
+exports.zipArchiveInputInfo = ts_utils_1.Validators.object({
+    type: exports.zipArchiveInputType,
+    originalPath: ts_utils_1.Validators.string,
+    archivePath: ts_utils_1.Validators.string
+});
+/**
+ * Validator for ZIP archive config information
+ * @public
+ */
+exports.zipArchiveConfigInfo = ts_utils_1.Validators.object({
+    type: exports.zipArchiveConfigType,
+    originalPath: ts_utils_1.Validators.string,
+    archivePath: ts_utils_1.Validators.string
+});
+/**
+ * Validator for ZIP archive manifest
+ * Compatible with existing tools from ts-res-browser-cli
+ * @public
+ */
+exports.zipArchiveManifest = ts_utils_1.Validators.object({
+    timestamp: ts_utils_1.Validators.string,
+    input: exports.zipArchiveInputInfo.optional(),
+    config: exports.zipArchiveConfigInfo.optional()
+});
+/**
+ * Validator for MIME type strings
+ * @public
+ */
+exports.mimeType = ts_utils_1.Validators.string;
+/**
+ * Converter for imported file
+ * @public
+ */
+exports.importedFile = ts_utils_1.Converters.strictObject({
+    name: ts_utils_1.Converters.string,
+    path: ts_utils_1.Converters.string,
+    content: ts_utils_1.Converters.string,
+    type: ts_utils_1.Converters.string // MIME type as string
+});
+/**
+ * Converter for imported directory structure (recursive)
+ * Note: Uses Converter pattern because Validators don't support recursion with self parameter
+ * @public
+ */
+exports.importedDirectory = ts_utils_1.Converters.generic((from, self, context) => {
+    return ts_utils_1.Converters.strictObject({
+        name: ts_utils_1.Converters.string,
+        files: ts_utils_1.Converters.arrayOf(exports.importedFile),
+        subdirectories: ts_utils_1.Converters.arrayOf(self)
+    }).convert(from, context);
+});
+/**
+ * Validator for system configuration (delegates to config packlet)
+ * This validates that the parsed JSON conforms to the system configuration schema
+ * @public
+ */
+exports.systemConfiguration = ts_utils_1.Validators.isA('system configuration', (value) => {
+    return config_1.Convert.systemConfiguration.convert(value).isSuccess();
+});
+//# sourceMappingURL=convert.js.map

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

@@ -0,0 +1,23 @@
+/**
+ * ZIP archive functionality for ts-res source file archives
+ *
+ * This packlet provides consolidated ZIP archive creation and loading functionality
+ * for source files, compatible with existing tools while using fflate for
+ * universal browser compatibility.
+ *
+ * @remarks
+ * ZIP archives contain source files for resource ingestion with directory
+ * structure preserved and optional validation but no processing or transformation.
+ * This is distinct from ZIP bundles which contain processed resource output.
+ *
+ * @packageDocumentation
+ */
+import * as Json from './json';
+import * as Convert from './convert';
+export { Json, Convert };
+export { ZipArchiveCreator } from './zipArchiveCreator';
+export { ZipArchiveLoader } from './zipArchiveLoader';
+export type { IZipArchivePathOptions, IZipArchiveFileTreeOptions, ZipArchiveOptions, IZipArchiveResult, IZipArchiveManifest, IZipArchiveLoadOptions, IZipArchiveLoadResult, IImportedFile, IImportedDirectory, ZipArchiveProgressCallback } from './types';
+export { createZipArchiveManifest, parseZipArchiveManifest, validateZipArchiveManifest, parseZipArchiveConfiguration, generateZipArchiveFilename, normalizePath, getDirectoryName, sanitizeFilename, isZipFile } from './zipArchiveFormat';
+export { ZipArchiveConstants } from './types';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1,95 @@
+"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.ZipArchiveConstants = exports.isZipFile = exports.sanitizeFilename = exports.getDirectoryName = exports.normalizePath = exports.generateZipArchiveFilename = exports.parseZipArchiveConfiguration = exports.validateZipArchiveManifest = exports.parseZipArchiveManifest = exports.createZipArchiveManifest = exports.ZipArchiveLoader = exports.ZipArchiveCreator = exports.Convert = exports.Json = void 0;
+/**
+ * ZIP archive functionality for ts-res source file archives
+ *
+ * This packlet provides consolidated ZIP archive creation and loading functionality
+ * for source files, compatible with existing tools while using fflate for
+ * universal browser compatibility.
+ *
+ * @remarks
+ * ZIP archives contain source files for resource ingestion with directory
+ * structure preserved and optional validation but no processing or transformation.
+ * This is distinct from ZIP bundles which contain processed resource output.
+ *
+ * @packageDocumentation
+ */
+const Json = __importStar(require("./json"));
+exports.Json = Json;
+const Convert = __importStar(require("./convert"));
+exports.Convert = Convert;
+// Core classes
+var zipArchiveCreator_1 = require("./zipArchiveCreator");
+Object.defineProperty(exports, "ZipArchiveCreator", { enumerable: true, get: function () { return zipArchiveCreator_1.ZipArchiveCreator; } });
+var zipArchiveLoader_1 = require("./zipArchiveLoader");
+Object.defineProperty(exports, "ZipArchiveLoader", { enumerable: true, get: function () { return zipArchiveLoader_1.ZipArchiveLoader; } });
+// Format utilities
+var zipArchiveFormat_1 = require("./zipArchiveFormat");
+Object.defineProperty(exports, "createZipArchiveManifest", { enumerable: true, get: function () { return zipArchiveFormat_1.createZipArchiveManifest; } });
+Object.defineProperty(exports, "parseZipArchiveManifest", { enumerable: true, get: function () { return zipArchiveFormat_1.parseZipArchiveManifest; } });
+Object.defineProperty(exports, "validateZipArchiveManifest", { enumerable: true, get: function () { return zipArchiveFormat_1.validateZipArchiveManifest; } });
+Object.defineProperty(exports, "parseZipArchiveConfiguration", { enumerable: true, get: function () { return zipArchiveFormat_1.parseZipArchiveConfiguration; } });
+Object.defineProperty(exports, "generateZipArchiveFilename", { enumerable: true, get: function () { return zipArchiveFormat_1.generateZipArchiveFilename; } });
+Object.defineProperty(exports, "normalizePath", { enumerable: true, get: function () { return zipArchiveFormat_1.normalizePath; } });
+Object.defineProperty(exports, "getDirectoryName", { enumerable: true, get: function () { return zipArchiveFormat_1.getDirectoryName; } });
+Object.defineProperty(exports, "sanitizeFilename", { enumerable: true, get: function () { return zipArchiveFormat_1.sanitizeFilename; } });
+Object.defineProperty(exports, "isZipFile", { enumerable: true, get: function () { return zipArchiveFormat_1.isZipFile; } });
+// Constants
+var types_1 = require("./types");
+Object.defineProperty(exports, "ZipArchiveConstants", { enumerable: true, get: function () { return types_1.ZipArchiveConstants; } });
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1,64 @@
+/**
+ * JSON representation of ZIP archive input information
+ * @public
+ */
+export interface IZipArchiveInputInfo {
+    /** Type of input (file or directory) */
+    type: 'file' | 'directory';
+    /** Original file/directory path */
+    originalPath: string;
+    /** Path within the archive (e.g., "input/mydir") */
+    archivePath: string;
+}
+/**
+ * JSON representation of ZIP archive config information
+ * @public
+ */
+export interface IZipArchiveConfigInfo {
+    /** Type of config (always 'file') */
+    type: 'file';
+    /** Original config file path */
+    originalPath: string;
+    /** Path within the archive (e.g., "config.json") */
+    archivePath: string;
+}
+/**
+ * JSON representation of a ZIP archive manifest
+ * Compatible with existing tools from ts-res-browser-cli
+ * @public
+ */
+export interface IZipArchiveManifest {
+    /** Archive creation timestamp */
+    timestamp: string;
+    /** Optional input source information */
+    input?: IZipArchiveInputInfo;
+    /** Optional configuration file information */
+    config?: IZipArchiveConfigInfo;
+}
+/**
+ * JSON representation of an imported file
+ * @public
+ */
+export interface IImportedFile {
+    /** File name */
+    name: string;
+    /** Full path within archive */
+    path: string;
+    /** File content as string */
+    content: string;
+    /** MIME type */
+    type: string;
+}
+/**
+ * JSON representation of an imported directory structure
+ * @public
+ */
+export interface IImportedDirectory {
+    /** Directory name */
+    name: string;
+    /** Files in this directory */
+    files: IImportedFile[];
+    /** Subdirectories */
+    subdirectories: IImportedDirectory[];
+}
+//# sourceMappingURL=json.d.ts.map

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

@@ -0,0 +1,24 @@
+"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 });
+//# sourceMappingURL=json.js.map

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-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 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