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

package/dist/ts-res.d.ts

@@ -14,6 +14,7 @@ import { ResultMap } from '@fgv/ts-utils';
 import { ValidatingCollector } from '@fgv/ts-utils';
 import { ValidatingConvertingCollector } from '@fgv/ts-utils';
 import { ValidatingResultMap } from '@fgv/ts-utils';
+import { Validator } from '@fgv/ts-utils';
 
 /**
  * An abstract decision represents a class of decisions with candidates
@@ -2099,6 +2100,20 @@ declare namespace Convert_11 {
     }
 }
 
+declare namespace Convert_12 {
+    export {
+        zipArchiveInputType,
+        zipArchiveConfigType,
+        zipArchiveInputInfo,
+        zipArchiveConfigInfo,
+        zipArchiveManifest,
+        mimeType,
+        importedFile,
+        importedDirectory,
+        systemConfiguration_2 as systemConfiguration
+    }
+}
+
 declare namespace Convert_2 {
     export {
         languageQualifierTypeConfig,
@@ -2221,6 +2236,17 @@ declare function createQualifierTypeFromSystemConfig(typeConfig: Config_2.ISyste
  */
 declare function createResourceTypeFromConfig(config: IResourceTypeConfig): Result<ResourceType>;
 
+/**
+ * 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
+ */
+declare function createZipArchiveManifest(inputType: 'file' | 'directory', originalPath: string, archivePath: string, configPath?: string): Json_2.IZipArchiveManifest;
+
 /**
  * Simple collectible implementation of {@link Decisions.IDecision | IDecision}.
  * @public
@@ -2533,6 +2559,22 @@ declare class FsItemImporter implements IImporter {
  */
 declare type FsItemResultDetail = 'failed' | 'skipped' | 'succeeded';
 
+/**
+ * Generate a timestamp-based filename for ZIP archives
+ * @param customName - Optional custom name prefix
+ * @returns Generated filename
+ * @public
+ */
+declare function generateZipArchiveFilename(customName?: string): string;
+
+/**
+ * Extract directory name from a file path
+ * @param path - File path
+ * @returns Directory name
+ * @public
+ */
+declare function getDirectoryName(path: string): string;
+
 /**
  * Gets the name for a resource ID.
  * @param id - The resource ID to get the name for.
@@ -3612,6 +3654,46 @@ declare interface IImportContext {
     readonly conditions?: ReadonlyArray<IConditionDecl>;
 }
 
+/**
+ * JSON representation of an imported directory structure
+ * @public
+ */
+declare interface IImportedDirectory {
+    /** Directory name */
+    name: string;
+    /** Files in this directory */
+    files: IImportedFile[];
+    /** Subdirectories */
+    subdirectories: IImportedDirectory[];
+}
+
+/**
+ * Imported directory structure
+ * @public
+ */
+declare type IImportedDirectory_2 = Json_2.IImportedDirectory;
+
+/**
+ * JSON representation of an imported file
+ * @public
+ */
+declare interface IImportedFile {
+    /** File name */
+    name: string;
+    /** Full path within archive */
+    path: string;
+    /** File content as string */
+    content: string;
+    /** MIME type */
+    type: string;
+}
+
+/**
+ * Imported file representation
+ * @public
+ */
+declare type IImportedFile_2 = Json_2.IImportedFile;
+
 /**
  * Generic interface for an importer than accepts a typed
  * {@link Import.IImportable | importable} item, extracts any resources
@@ -4068,6 +4150,19 @@ declare class ImportContext implements IValidatedImportContext {
     static forContainerImport(container?: ResourceJson.Normalized.IContainerContextDecl, importer?: ImportContext): Result<ImportContext | undefined>;
 }
 
+/**
+ * Converter for imported directory structure (recursive)
+ * Note: Uses Converter pattern because Validators don't support recursion with self parameter
+ * @public
+ */
+declare const importedDirectory: Converter<Json_2.IImportedDirectory>;
+
+/**
+ * Converter for imported file
+ * @public
+ */
+declare const importedFile: Converter<Json_2.IImportedFile>;
+
 /**
  * `Converter` for a normalized {@link ResourceJson.Normalized.IImporterResourceCandidateDecl | importer resource candidate declaration}.
  * @public
@@ -5402,6 +5497,14 @@ declare interface ISystemTerritoryQualifierTypeConfig extends IQualifierTypeConf
     systemType: 'territory';
 }
 
+/**
+ * Validate ZIP file extension
+ * @param filename - Filename to validate
+ * @returns True if filename has .zip extension
+ * @public
+ */
+declare function isZipFile(filename: string): boolean;
+
 /**
  * Configuration for {@link QualifierTypes.TerritoryQualifierType | territory qualifier type} configuration.
  * @public
@@ -5575,6 +5678,111 @@ declare interface IValidatingSimpleContextQualifierProviderCreateParams {
     qualifierValues?: Record<string, string>;
 }
 
+/**
+ * JSON representation of ZIP archive config information
+ * @public
+ */
+declare 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;
+}
+
+/**
+ * Options for creating a ZIP archive buffer from a file tree
+ * @public
+ */
+declare interface IZipArchiveFileTreeOptions {
+    /** Input file or directory */
+    inputItem?: FileTree.FileTreeItem;
+    /** Optional configuration file */
+    configItem?: FileTree.IFileTreeFileItem;
+}
+
+/**
+ * JSON representation of ZIP archive input information
+ * @public
+ */
+declare 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;
+}
+
+/**
+ * Options for loading a ZIP archive
+ * @public
+ */
+declare interface IZipArchiveLoadOptions {
+    /** Validate manifest strictly */
+    strictManifestValidation?: boolean;
+}
+
+/**
+ * Result of ZIP archive loading
+ * @public
+ */
+declare interface IZipArchiveLoadResult {
+    /** Parsed archive manifest */
+    manifest: IZipArchiveManifest_2 | undefined;
+    /** Loaded configuration */
+    config: Model.ISystemConfiguration | undefined;
+    /** All files extracted from the archive */
+    files: IImportedFile_2[];
+    /** Directory structure if available */
+    directory: IImportedDirectory_2 | undefined;
+}
+
+/**
+ * JSON representation of a ZIP archive manifest
+ * Compatible with existing tools from ts-res-browser-cli
+ * @public
+ */
+declare interface IZipArchiveManifest {
+    /** Archive creation timestamp */
+    timestamp: string;
+    /** Optional input source information */
+    input?: IZipArchiveInputInfo;
+    /** Optional configuration file information */
+    config?: IZipArchiveConfigInfo;
+}
+
+/**
+ * Standardized ZIP archive manifest format (compatible with existing tools)
+ * @public
+ */
+declare type IZipArchiveManifest_2 = Json_2.IZipArchiveManifest;
+
+/**
+ * Options for creating a ZIP archive buffer
+ * @public
+ */
+declare interface IZipArchivePathOptions {
+    /** File or directory path to include in the archive */
+    inputPath?: string;
+    /** Optional configuration file path */
+    configPath?: string;
+}
+
+/**
+ * Result of ZIP archive buffer creation
+ * @public
+ */
+declare interface IZipArchiveResult {
+    /** Raw ZIP data buffer */
+    zipBuffer: Uint8Array;
+    /** Archive manifest with metadata */
+    manifest: IZipArchiveManifest_2;
+    /** Total ZIP size in bytes */
+    size: number;
+}
+
 /**
  * Joins a list of {@link ResourceId | resource ID} or {@link ResourceName | resource name} with
  * to create a new {@link ResourceId | resource ID}. Returns `undefined` if no names are defined.
@@ -5622,6 +5830,16 @@ declare namespace Json {
     }
 }
 
+declare namespace Json_2 {
+    export {
+        IZipArchiveInputInfo,
+        IZipArchiveConfigInfo,
+        IZipArchiveManifest,
+        IImportedFile,
+        IImportedDirectory
+    }
+}
+
 /**
  * {@link Import.Importers.IImporter | Importer} implementation which imports resources from a JSON object.
  * @public
@@ -6090,6 +6308,12 @@ declare function mergeLooseCandidate(candidate: Normalized.IImporterResourceCand
  */
 declare function mergeLooseResource(resource: Normalized.IImporterResourceDecl, baseName?: string, baseConditions?: ReadonlyArray<Json.ILooseConditionDecl>): Result<Normalized.ILooseResourceDecl>;
 
+/**
+ * Validator for MIME type strings
+ * @public
+ */
+declare const mimeType: Validator<string>;
+
 /**
  * Minimum valid priority for a condition.
  * @public
@@ -6193,6 +6417,14 @@ declare namespace Normalized {
     }
 }
 
+/**
+ * Normalize path separators for cross-platform compatibility
+ * @param path - Path to normalize
+ * @returns Normalized path
+ * @public
+ */
+declare function normalizePath(path: string): string;
+
 /**
  * Overall cache metrics across all cache types.
  * @public
@@ -6247,6 +6479,22 @@ declare function parseQualifierDefaultValuesTokenParts(token: string): Result<IQ
  */
 declare function parseQualifierDefaultValueTokenParts(token: string): Result<IQualifierDefaultValueTokenParts>;
 
+/**
+ * Parse and validate configuration JSON
+ * @param configData - JSON string containing configuration
+ * @returns Result containing validated configuration
+ * @public
+ */
+declare function parseZipArchiveConfiguration(configData: string): Result<Model.ISystemConfiguration>;
+
+/**
+ * Parse and validate a ZIP archive manifest
+ * @param manifestData - JSON string containing manifest data
+ * @returns Result containing validated manifest
+ * @public
+ */
+declare function parseZipArchiveManifest(manifestData: string): Result<Json_2.IZipArchiveManifest>;
+
 /**
  * {@link Import.Importers.IImporter | Importer} implementation which imports resources from a `FileTree`
  * given a path.
@@ -8400,6 +8648,14 @@ declare namespace Runtime {
 }
 export { Runtime }
 
+/**
+ * Create a safe filename by removing invalid characters
+ * @param filename - Original filename
+ * @returns Sanitized filename
+ * @public
+ */
+declare function sanitizeFilename(filename: string): string;
+
 /**
  * @internal
  */
@@ -8577,6 +8833,13 @@ declare class SystemConfiguration {
  */
 declare const systemConfiguration: ObjectConverter<ISystemConfiguration, unknown>;
 
+/**
+ * Validator for system configuration (delegates to config packlet)
+ * This validates that the parsed JSON conforms to the system configuration schema
+ * @public
+ */
+declare const systemConfiguration_2: Validator<Model.ISystemConfiguration>;
+
 /**
  * A `Converter` for {@link QualifierTypes.Config.ISystemLanguageQualifierTypeConfig | SystemLanguageQualifierTypeConfig} objects.
  * @returns A `Converter` for {@link QualifierTypes.Config.ISystemLanguageQualifierTypeConfig | SystemLanguageQualifierTypeConfig} objects.
@@ -9057,6 +9320,14 @@ declare const validatedContextQualifierValueDecl: Converter<IValidatedContextQua
  */
 declare const validatedQualifierDecl: Converter<IValidatedQualifierDecl, IQualifierDeclConvertContext>;
 
+/**
+ * Validate a ZIP archive manifest object
+ * @param manifest - Object to validate as manifest
+ * @returns Result containing validated manifest
+ * @public
+ */
+declare function validateZipArchiveManifest(manifest: unknown): Result<Json_2.IZipArchiveManifest>;
+
 /**
  * A {@link Runtime.SimpleContextQualifierProvider | SimpleContextQualifierProvider} with a
  * {@link Runtime.Context.ContextQualifierProviderValidator | validator} property that enables
@@ -9085,4 +9356,194 @@ declare class ValidatingSimpleContextQualifierProvider extends SimpleContextQual
     static create(params: IValidatingSimpleContextQualifierProviderCreateParams): Result<ValidatingSimpleContextQualifierProvider>;
 }
 
+declare namespace ZipArchive {
+    export {
+        Json_2 as Json,
+        Convert_12 as Convert,
+        ZipArchiveCreator,
+        ZipArchiveLoader,
+        IZipArchivePathOptions,
+        IZipArchiveFileTreeOptions,
+        ZipArchiveOptions,
+        IZipArchiveResult,
+        IZipArchiveManifest_2 as IZipArchiveManifest,
+        IZipArchiveLoadOptions,
+        IZipArchiveLoadResult,
+        IImportedFile_2 as IImportedFile,
+        IImportedDirectory_2 as IImportedDirectory,
+        ZipArchiveProgressCallback,
+        createZipArchiveManifest,
+        parseZipArchiveManifest,
+        validateZipArchiveManifest,
+        parseZipArchiveConfiguration,
+        generateZipArchiveFilename,
+        normalizePath,
+        getDirectoryName,
+        sanitizeFilename,
+        isZipFile,
+        ZipArchiveConstants
+    }
+}
+export { ZipArchive }
+
+/**
+ * Validator for ZIP archive config information
+ * @public
+ */
+declare const zipArchiveConfigInfo: Validator<Json_2.IZipArchiveConfigInfo>;
+
+/**
+ * Validator for ZIP archive config type
+ * @public
+ */
+declare const zipArchiveConfigType: Validator<'file'>;
+
+/**
+ * Constants for ZIP archive structure
+ * @public
+ */
+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";
+};
+
+/**
+ * ZIP archive creator using fflate for universal compatibility
+ * @public
+ */
+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;
+}
+
+/**
+ * Validator for ZIP archive input information
+ * @public
+ */
+declare const zipArchiveInputInfo: Validator<Json_2.IZipArchiveInputInfo>;
+
+/**
+ * Validator for ZIP archive input type
+ * @public
+ */
+declare const zipArchiveInputType: Validator<'file' | 'directory'>;
+
+/**
+ * ZIP archive loader extending ts-extras foundation
+ * @public
+ */
+declare class ZipArchiveLoader {
+    /**
+     * Load ZIP archive from File object (Browser)
+     * @param file - File object from file input
+     * @param options - Loading options
+     * @param onProgress - Optional progress callback
+     * @returns Result containing loaded archive data
+     */
+    loadFromFile(file: File, options?: IZipArchiveLoadOptions, onProgress?: ZipArchiveProgressCallback): Promise<Result<IZipArchiveLoadResult>>;
+    /**
+     * Load ZIP archive from ArrayBuffer (Universal)
+     * @param buffer - ZIP data buffer
+     * @param options - Loading options
+     * @param onProgress - Optional progress callback
+     * @returns Result containing loaded archive data
+     */
+    loadFromBuffer(buffer: ArrayBuffer, options?: IZipArchiveLoadOptions, onProgress?: ZipArchiveProgressCallback): Promise<Result<IZipArchiveLoadResult>>;
+    /**
+     * Load manifest from ZIP using ZipFileTreeAccessors
+     * @param zipAccessors - ZIP file tree accessors
+     * @returns Result containing parsed manifest
+     */
+    private _loadManifestFromAccessors;
+    /**
+     * Load configuration from ZIP using ZipFileTreeAccessors
+     * @param zipAccessors - ZIP file tree accessors
+     * @param manifest - Parsed manifest (may be undefined)
+     * @param options - Loading options
+     * @returns Result containing parsed configuration
+     */
+    private _loadConfigurationFromAccessors;
+    /**
+     * Extract files and directory structure from ZIP
+     * @param zipAccessors - ZIP file tree accessors
+     * @param onProgress - Optional progress callback
+     * @returns Result containing files and directory structure
+     */
+    private _extractFilesFromAccessors;
+    /**
+     * Recursively process file tree items
+     * @param zipAccessors - ZIP file tree accessors
+     * @param currentPath - Current directory path
+     * @param items - Items to process
+     * @param files - Files collection
+     * @param directories - Directories collection
+     * @param onProgress - Optional progress callback
+     * @param processed - Processing counter
+     */
+    private _processFileTreeItems;
+    /**
+     * Build directory structure from files
+     * @param files - Extracted files
+     * @param directories - Directories map
+     * @returns Root directory structure or null
+     */
+    private _buildDirectoryStructure;
+    /**
+     * Get file MIME type based on extension
+     * @param filename - Filename
+     * @returns MIME type
+     */
+    private _getFileType;
+}
+
+/**
+ * Validator for ZIP archive manifest
+ * Compatible with existing tools from ts-res-browser-cli
+ * @public
+ */
+declare const zipArchiveManifest: Validator<Json_2.IZipArchiveManifest>;
+
+/**
+ * Options for creating a ZIP archive buffer
+ * @public
+ */
+declare type ZipArchiveOptions = IZipArchivePathOptions | IZipArchiveFileTreeOptions;
+
+/**
+ * Progress callback for ZIP operations
+ * @public
+ */
+declare type ZipArchiveProgressCallback = (stage: 'reading-file' | 'parsing-zip' | 'loading-manifest' | 'loading-config' | 'extracting-files' | 'processing-resources' | 'creating-zip', progress: number, // 0-100
+details: string) => void;
+
 export { }

package/lib/index.d.ts

@@ -10,6 +10,7 @@ import * as Resources from './packlets/resources';
 import * as ResourceTypes from './packlets/resource-types';
 import * as Import from './packlets/import';
 import * as Runtime from './packlets/runtime';
+import * as ZipArchive from './packlets/zip-archive';
 export * from './packlets/common';
 import { Condition, ConditionSet } from './packlets/conditions';
 import { Decision } from './packlets/decisions';
@@ -19,5 +20,5 @@ import { ResourceType } from './packlets/resource-types';
 import { Resource, ResourceCandidate, ResourceManagerBuilder } from './packlets/resources';
 import { IResourceManager, ResourceResolver } from './packlets/runtime';
 import { BundleBuilder, BundleLoader } from './packlets/bundle';
-export { Bundle, BundleBuilder, BundleLoader, Condition, Conditions, ConditionSet, Config, Context, Decision, Decisions, Import, IResourceManager, Qualifier, QualifierType, QualifierTypes, Qualifiers, Resource, ResourceCandidate, ResourceJson, ResourceResolver, ResourceManagerBuilder, ResourceType, ResourceTypes, Resources, Runtime };
+export { Bundle, BundleBuilder, BundleLoader, Condition, Conditions, ConditionSet, Config, Context, Decision, Decisions, Import, IResourceManager, Qualifier, QualifierType, QualifierTypes, Qualifiers, Resource, ResourceCandidate, ResourceJson, ResourceResolver, ResourceManagerBuilder, ResourceType, ResourceTypes, Resources, Runtime, ZipArchive };
 //# sourceMappingURL=index.d.ts.map

package/lib/index.js

@@ -57,7 +57,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Runtime = exports.Resources = exports.ResourceTypes = exports.ResourceType = exports.ResourceManagerBuilder = exports.ResourceResolver = exports.ResourceJson = exports.ResourceCandidate = exports.Resource = exports.Qualifiers = exports.QualifierTypes = exports.QualifierType = exports.Qualifier = exports.Import = exports.Decisions = exports.Decision = exports.Context = exports.Config = exports.ConditionSet = exports.Conditions = exports.Condition = exports.BundleLoader = exports.BundleBuilder = exports.Bundle = void 0;
+exports.ZipArchive = exports.Runtime = exports.Resources = exports.ResourceTypes = exports.ResourceType = exports.ResourceManagerBuilder = exports.ResourceResolver = exports.ResourceJson = exports.ResourceCandidate = exports.Resource = exports.Qualifiers = exports.QualifierTypes = exports.QualifierType = exports.Qualifier = exports.Import = exports.Decisions = exports.Decision = exports.Context = exports.Config = exports.ConditionSet = exports.Conditions = exports.Condition = exports.BundleLoader = exports.BundleBuilder = exports.Bundle = void 0;
 const Bundle = __importStar(require("./packlets/bundle"));
 exports.Bundle = Bundle;
 const QualifierTypes = __importStar(require("./packlets/qualifier-types"));
@@ -82,6 +82,8 @@ const Import = __importStar(require("./packlets/import"));
 exports.Import = Import;
 const Runtime = __importStar(require("./packlets/runtime"));
 exports.Runtime = Runtime;
+const ZipArchive = __importStar(require("./packlets/zip-archive"));
+exports.ZipArchive = ZipArchive;
 __exportStar(require("./packlets/common"), exports);
 const conditions_1 = require("./packlets/conditions");
 Object.defineProperty(exports, "Condition", { enumerable: true, get: function () { return conditions_1.Condition; } });

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

@@ -0,0 +1,52 @@
+import { Validator, Converter } from '@fgv/ts-utils';
+import * as Json from './json';
+import { Model as ConfigModel } from '../config';
+/**
+ * Validator for ZIP archive input type
+ * @public
+ */
+export declare const zipArchiveInputType: Validator<'file' | 'directory'>;
+/**
+ * Validator for ZIP archive config type
+ * @public
+ */
+export declare const zipArchiveConfigType: Validator<'file'>;
+/**
+ * Validator for ZIP archive input information
+ * @public
+ */
+export declare const zipArchiveInputInfo: Validator<Json.IZipArchiveInputInfo>;
+/**
+ * Validator for ZIP archive config information
+ * @public
+ */
+export declare const zipArchiveConfigInfo: Validator<Json.IZipArchiveConfigInfo>;
+/**
+ * Validator for ZIP archive manifest
+ * Compatible with existing tools from ts-res-browser-cli
+ * @public
+ */
+export declare const zipArchiveManifest: Validator<Json.IZipArchiveManifest>;
+/**
+ * Validator for MIME type strings
+ * @public
+ */
+export declare const mimeType: Validator<string>;
+/**
+ * Converter for imported file
+ * @public
+ */
+export declare const importedFile: Converter<Json.IImportedFile>;
+/**
+ * Converter for imported directory structure (recursive)
+ * Note: Uses Converter pattern because Validators don't support recursion with self parameter
+ * @public
+ */
+export declare const importedDirectory: Converter<Json.IImportedDirectory>;
+/**
+ * Validator for system configuration (delegates to config packlet)
+ * This validates that the parsed JSON conforms to the system configuration schema
+ * @public
+ */
+export declare const systemConfiguration: Validator<ConfigModel.ISystemConfiguration>;
+//# sourceMappingURL=convert.d.ts.map