@fgv/ts-res 5.0.1-8 → 5.0.1

package/dist/index.browser.js

@@ -0,0 +1,53 @@
+/*
+ * 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.
+ */
+// Browser entry point - excludes Node.js filesystem dependencies
+import * as Bundle from './packlets/bundle';
+import * as QualifierTypes from './packlets/qualifier-types';
+import * as Qualifiers from './packlets/qualifiers';
+import * as Conditions from './packlets/conditions';
+// eslint-disable-next-line @rushstack/packlets/mechanics -- browser-specific entry point excludes Node.js fs dependencies
+import * as Config from './packlets/config/index.browser';
+import * as Context from './packlets/context';
+import * as Decisions from './packlets/decisions';
+import * as ResourceJson from './packlets/resource-json';
+import * as Resources from './packlets/resources';
+import * as ResourceTypes from './packlets/resource-types';
+// eslint-disable-next-line @rushstack/packlets/mechanics -- browser-specific entry point excludes Node.js fs dependencies
+import * as Import from './packlets/import/index.browser';
+import * as Runtime from './packlets/runtime';
+// eslint-disable-next-line @rushstack/packlets/mechanics -- browser-specific entry point excludes Node.js fs dependencies
+import * as ZipArchive from './packlets/zip-archive/index.browser';
+export * from './packlets/common';
+import { Condition, ConditionSet } from './packlets/conditions';
+import { Decision } from './packlets/decisions';
+import { QualifierType } from './packlets/qualifier-types';
+import { Qualifier } from './packlets/qualifiers';
+import { ResourceType } from './packlets/resource-types';
+import { Resource, ResourceCandidate, ResourceManagerBuilder } from './packlets/resources';
+import { ResourceResolver } from './packlets/runtime';
+import { BundleBuilder, BundleLoader } from './packlets/bundle';
+export { Bundle, BundleBuilder, BundleLoader, Condition, Conditions, ConditionSet, Config, Context, Decision, Decisions, Import, Qualifier, QualifierType, QualifierTypes, Qualifiers, Resource, ResourceCandidate, ResourceJson, ResourceResolver, ResourceManagerBuilder, ResourceType, ResourceTypes, Resources, Runtime, ZipArchive };
+// Excluded from browser:
+// - Config: SystemConfiguration.loadFromFile() (requires Node.js fs via JsonFile)
+// - Import: PathImporter, FsItemImporter, FsItem.createForPath() (require Node.js fs)
+// - ZipArchive: ZipArchiveCreator methods using file paths (require Node.js fs)
+//# sourceMappingURL=index.browser.js.map

package/dist/index.js

@@ -0,0 +1,45 @@
+/*
+ * 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 * as Bundle from './packlets/bundle';
+import * as QualifierTypes from './packlets/qualifier-types';
+import * as Qualifiers from './packlets/qualifiers';
+import * as Conditions from './packlets/conditions';
+import * as Config from './packlets/config';
+import * as Context from './packlets/context';
+import * as Decisions from './packlets/decisions';
+import * as ResourceJson from './packlets/resource-json';
+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';
+import { QualifierType } from './packlets/qualifier-types';
+import { Qualifier } from './packlets/qualifiers';
+import { ResourceType } from './packlets/resource-types';
+import { Resource, ResourceCandidate, ResourceManagerBuilder } from './packlets/resources';
+import { ResourceResolver } from './packlets/runtime';
+import { BundleBuilder, BundleLoader } from './packlets/bundle';
+export { Bundle, BundleBuilder, BundleLoader, Condition, Conditions, ConditionSet, Config, Context, Decision, Decisions, Import, Qualifier, QualifierType, QualifierTypes, Qualifiers, Resource, ResourceCandidate, ResourceJson, ResourceResolver, ResourceManagerBuilder, ResourceType, ResourceTypes, Resources, Runtime, ZipArchive };
+//# sourceMappingURL=index.js.map

package/dist/packlets/bundle/bundleBuilder.js

@@ -0,0 +1,130 @@
+/*
+ * 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 { succeed, Hash } from '@fgv/ts-utils';
+import { getPredefinedSystemConfiguration } from '../config';
+import { BundleNormalizer } from './bundleNormalizer';
+/**
+ * Builder for creating resource bundles from a ResourceManagerBuilder.
+ * Handles the compilation, configuration extraction, and integrity verification
+ * needed to create a complete, portable bundle.
+ * @public
+ */
+export class BundleBuilder {
+    /**
+     * Creates a resource bundle from a ResourceManagerBuilder.
+     * @param builder - The ResourceManagerBuilder containing the resources to bundle
+     * @param systemConfig - The SystemConfiguration used to create the builder
+     * @param params - Optional parameters for bundle creation
+     * @returns Success with the created bundle if successful, Failure with error message otherwise
+     * @public
+     */
+    static create(builder, systemConfig, params) {
+        var _a;
+        /* c8 ignore next 2 - defense in depth */
+        params = params !== null && params !== void 0 ? params : {};
+        const hashNormalizer = (_a = params.hashNormalizer) !== null && _a !== void 0 ? _a : new Hash.Crc32Normalizer();
+        const builderToUse = params.normalize === true
+            ? BundleNormalizer.normalize(builder, systemConfig)
+            : /* c8 ignore next 1 - is tested but coverage gets confused */
+                succeed(builder);
+        return builderToUse.onSuccess((targetBuilder) => {
+            return systemConfig.getConfig().onSuccess((config) => {
+                return targetBuilder.getCompiledResourceCollection().onSuccess((compiledCollection) => {
+                    return BundleBuilder._generateChecksum(compiledCollection, hashNormalizer).onSuccess((checksum) => {
+                        var _a;
+                        /* c8 ignore next 1 - defense in depth */
+                        const dateBuilt = (_a = params.dateBuilt) !== null && _a !== void 0 ? _a : new Date().toISOString();
+                        const metadata = {
+                            dateBuilt,
+                            checksum,
+                            version: params.version,
+                            description: params.description
+                        };
+                        const bundle = {
+                            metadata,
+                            config,
+                            compiledCollection
+                        };
+                        return succeed(bundle);
+                    });
+                });
+            });
+        });
+    }
+    /**
+     * Creates a resource bundle from a ResourceManagerBuilder using a predefined system configuration.
+     * This is a convenience method for the common case of using predefined configurations.
+     * @param builder - The ResourceManagerBuilder containing the resources to bundle
+     * @param configName - The name of the predefined system configuration used
+     * @param params - Optional parameters for bundle creation
+     * @returns Success with the created bundle if successful, Failure with error message otherwise
+     * @public
+     */
+    static createFromPredefined(builder, configName, params) {
+        var _a;
+        /* c8 ignore next 1 */
+        params = params !== null && params !== void 0 ? params : {};
+        const hashNormalizer = (_a = params.hashNormalizer) !== null && _a !== void 0 ? _a : new Hash.Crc32Normalizer();
+        // Determine which builder to use based on normalization setting
+        const builderToUse = params.normalize
+            ? BundleNormalizer.normalizeFromPredefined(builder, configName)
+            : succeed(builder);
+        return builderToUse.onSuccess((targetBuilder) => {
+            return getPredefinedSystemConfiguration(configName).onSuccess((systemConfig) => {
+                return systemConfig.getConfig().onSuccess((config) => {
+                    return targetBuilder.getCompiledResourceCollection().onSuccess((compiledCollection) => {
+                        return BundleBuilder._generateChecksum(compiledCollection, hashNormalizer).onSuccess((checksum) => {
+                            var _a;
+                            /* c8 ignore next 1 - defense in depth */
+                            const dateBuilt = (_a = params.dateBuilt) !== null && _a !== void 0 ? _a : new Date().toISOString();
+                            const metadata = {
+                                dateBuilt,
+                                checksum,
+                                version: params.version,
+                                /* c8 ignore next 1 - defense in depth */
+                                description: params === null || params === void 0 ? void 0 : params.description
+                            };
+                            const bundle = {
+                                metadata,
+                                config,
+                                compiledCollection
+                            };
+                            return succeed(bundle);
+                        });
+                    });
+                });
+            });
+        });
+    }
+    /**
+     * Generates a hash checksum for the compiled resource collection.
+     * The checksum is calculated using the provided hash normalizer.
+     * @param compiledCollection - The compiled resource collection to generate checksum for
+     * @param hashNormalizer - The hash normalizer to use for checksum generation
+     * @returns Success with the checksum string if successful, Failure otherwise
+     * @internal
+     */
+    static _generateChecksum(compiledCollection, hashNormalizer) {
+        return hashNormalizer.computeHash(compiledCollection);
+    }
+}
+//# sourceMappingURL=bundleBuilder.js.map

package/dist/packlets/bundle/bundleLoader.js

@@ -0,0 +1,101 @@
+/*
+ * 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 { succeed, fail, Hash } from '@fgv/ts-utils';
+import { CompiledResourceCollection } from '../runtime';
+import { SystemConfiguration } from '../config';
+/**
+ * Loader for creating an IResourceManager from a resource bundle.
+ * Handles integrity verification and reconstruction of the runtime resource manager.
+ * @public
+ */
+export class BundleLoader {
+    /**
+     * Creates an IResourceManager from a resource bundle.
+     * @param params - Parameters for bundle loading including the bundle and options
+     * @returns Success with the IResourceManager if successful, Failure with error message otherwise
+     * @public
+     */
+    static createManagerFromBundle(params) {
+        var _a, _b;
+        /* c8 ignore next 1 - defense in depth */
+        const hashNormalizer = (_a = params.hashNormalizer) !== null && _a !== void 0 ? _a : new Hash.Crc32Normalizer();
+        return BundleLoader._verifyBundleIntegrity(params.bundle, (_b = params.skipChecksumVerification) !== null && _b !== void 0 ? _b : false, hashNormalizer).onSuccess(() => {
+            return BundleLoader._createSystemConfiguration(params.bundle).onSuccess((systemConfig) => {
+                return BundleLoader._createCompiledResourceCollection(params.bundle, systemConfig.qualifierTypes, systemConfig.resourceTypes);
+            });
+        });
+    }
+    /**
+     * Verifies the integrity of a bundle by checking its checksum.
+     * @param bundle - The bundle to verify
+     * @param skipVerification - Whether to skip verification
+     * @param hashNormalizer - The hash normalizer to use for verification
+     * @returns Success if verification passes or is skipped, Failure otherwise
+     * @internal
+     */
+    static _verifyBundleIntegrity(bundle, skipVerification, hashNormalizer) {
+        if (skipVerification) {
+            return succeed(true);
+        }
+        return BundleLoader._generateChecksum(bundle.compiledCollection, hashNormalizer).onSuccess((calculatedChecksum) => {
+            if (calculatedChecksum !== bundle.metadata.checksum) {
+                return fail(`Bundle integrity verification failed: expected checksum ${bundle.metadata.checksum}, got ${calculatedChecksum}`);
+            }
+            return succeed(true);
+        });
+    }
+    /**
+     * Generates a hash checksum for the compiled resource collection.
+     * @param compiledCollection - The compiled resource collection to generate checksum for
+     * @param hashNormalizer - The hash normalizer to use for checksum generation
+     * @returns Success with the checksum string if successful, Failure otherwise
+     * @internal
+     */
+    static _generateChecksum(compiledCollection, hashNormalizer) {
+        return hashNormalizer.computeHash(compiledCollection);
+    }
+    /**
+     * Creates a SystemConfiguration from the bundle's configuration.
+     * @param bundle - The bundle containing the configuration
+     * @returns Success with the SystemConfiguration if successful, Failure otherwise
+     * @internal
+     */
+    static _createSystemConfiguration(bundle) {
+        return SystemConfiguration.create(bundle.config);
+    }
+    /**
+     * Creates a CompiledResourceCollection from the bundle.
+     * @param bundle - The bundle to load
+     * @param qualifierTypes - The qualifier type collector from the system configuration
+     * @param resourceTypes - The resource type collector from the system configuration
+     * @returns Success with the CompiledResourceCollection if successful, Failure otherwise
+     * @internal
+     */
+    static _createCompiledResourceCollection(bundle, qualifierTypes, resourceTypes) {
+        return CompiledResourceCollection.create({
+            compiledCollection: bundle.compiledCollection,
+            qualifierTypes,
+            resourceTypes
+        });
+    }
+}
+//# sourceMappingURL=bundleLoader.js.map

package/dist/packlets/bundle/bundleNormalizer.js

@@ -0,0 +1,138 @@
+/*
+ * 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 { succeed, MessageAggregator } from '@fgv/ts-utils';
+import { ResourceManagerBuilder } from '../resources';
+import { ResourceCandidate } from '../resources';
+import { Condition, ConditionSet } from '../conditions';
+/**
+ * Normalizes ResourceManagerBuilder instances to ensure consistent ordering
+ * of internal entities, enabling order-independent bundle checksums.
+ *
+ * The normalization process rebuilds the ResourceManagerBuilder from the ground up
+ * in a canonical order to ensure identical index assignments regardless of
+ * original construction order.
+ * @public
+ */
+export class BundleNormalizer {
+    /**
+     * Creates a normalized ResourceManagerBuilder from an existing builder.
+     * The normalized builder will have identical entities but arranged in
+     * canonical order to ensure consistent index assignments.
+     *
+     * @param originalBuilder - The ResourceManagerBuilder to normalize
+     * @param systemConfig - The SystemConfiguration used to create the original builder
+     * @returns Success with the normalized ResourceManagerBuilder if successful, Failure otherwise
+     */
+    static normalize(originalBuilder, systemConfig) {
+        // Create a fresh builder using the same system configuration
+        return ResourceManagerBuilder.create({
+            qualifiers: systemConfig.qualifiers,
+            resourceTypes: systemConfig.resourceTypes
+        }).onSuccess((normalizedBuilder) => {
+            return BundleNormalizer._addNormalizedResources(originalBuilder, normalizedBuilder).onSuccess(() => succeed(normalizedBuilder));
+        });
+    }
+    /**
+     * Creates a normalized ResourceManagerBuilder using a predefined system configuration.
+     * This is a convenience method for the common case of using predefined configurations.
+     *
+     * @param originalBuilder - The ResourceManagerBuilder to normalize
+     * @param configName - The name of the predefined system configuration used
+     * @returns Success with the normalized ResourceManagerBuilder if successful, Failure otherwise
+     */
+    static normalizeFromPredefined(originalBuilder, configName) {
+        return ResourceManagerBuilder.createPredefined(configName).onSuccess((normalizedBuilder) => {
+            return BundleNormalizer._addNormalizedResources(originalBuilder, normalizedBuilder).onSuccess(() => succeed(normalizedBuilder));
+        });
+    }
+    /**
+     * Normalizes all conditions from the original builder by adding them to the
+     * normalized builder in sorted order using loose condition declarations.
+     *
+     * @param originalBuilder - The source ResourceManagerBuilder
+     * @param normalizedBuilder - The target normalized ResourceManagerBuilder
+     * @returns Success if all conditions were normalized successfully, Failure otherwise
+     * @internal
+     */
+    static _normalizeConditions(originalBuilder, normalizedBuilder) {
+        const conditions = Array.from(originalBuilder.conditions.values()).sort(Condition.compare);
+        const errors = new MessageAggregator();
+        for (const condition of conditions) {
+            const looseDecl = condition.toLooseConditionDecl();
+            normalizedBuilder.addCondition(looseDecl).aggregateError(errors);
+        }
+        return errors.returnOrReport(succeed(true));
+    }
+    /**
+     * Normalizes all condition sets from the original builder by adding them to the
+     * normalized builder in sorted order using loose condition set declarations.
+     *
+     * @param originalBuilder - The source ResourceManagerBuilder
+     * @param normalizedBuilder - The target normalized ResourceManagerBuilder
+     * @returns Success if all condition sets were normalized successfully, Failure otherwise
+     * @internal
+     */
+    static _normalizeConditionSets(originalBuilder, normalizedBuilder) {
+        const conditionSets = Array.from(originalBuilder.conditionSets.values()).sort(ConditionSet.compare);
+        const errors = new MessageAggregator();
+        for (const conditionSet of conditionSets) {
+            const conditions = conditionSet.toConditionSetArrayDecl();
+            normalizedBuilder.addConditionSet(conditions).aggregateError(errors);
+        }
+        return errors.returnOrReport(succeed(true));
+    }
+    /**
+     * Normalizes all candidates by sorting them first by resource ID, then by condition set.
+     *
+     * @param originalBuilder - The source ResourceManagerBuilder
+     * @param normalizedBuilder - The target normalized ResourceManagerBuilder
+     * @returns Success if all candidates were normalized successfully, Failure otherwise
+     * @internal
+     */
+    static _normalizeCandidates(originalBuilder, normalizedBuilder) {
+        const candidates = Array.from(originalBuilder.getAllCandidates()).sort((c1, c2) => {
+            const idCompare = c1.id.localeCompare(c2.id);
+            return idCompare !== 0 ? idCompare : ResourceCandidate.compare(c1, c2);
+        });
+        const errors = new MessageAggregator();
+        for (const candidate of candidates) {
+            const decl = candidate.toLooseResourceCandidateDecl();
+            normalizedBuilder.addLooseCandidate(decl).aggregateError(errors);
+        }
+        return errors.returnOrReport(succeed(true));
+    }
+    /**
+     * Adds normalized resources to the target builder by first normalizing conditions,
+     * then condition sets, then candidates.
+     *
+     * @param originalBuilder - The source ResourceManagerBuilder
+     * @param normalizedBuilder - The target normalized ResourceManagerBuilder
+     * @returns Success if all resources were added successfully, Failure otherwise
+     * @internal
+     */
+    static _addNormalizedResources(originalBuilder, normalizedBuilder) {
+        return BundleNormalizer._normalizeConditions(originalBuilder, normalizedBuilder)
+            .onSuccess(() => BundleNormalizer._normalizeConditionSets(originalBuilder, normalizedBuilder))
+            .onSuccess(() => BundleNormalizer._normalizeCandidates(originalBuilder, normalizedBuilder));
+    }
+}
+//# sourceMappingURL=bundleNormalizer.js.map

package/dist/packlets/bundle/bundleUtils.js

@@ -0,0 +1,113 @@
+/*
+ * 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 { succeed, fail } from '@fgv/ts-utils';
+import { SystemConfiguration } from '../config';
+import { bundle as bundleConverter } from './convert';
+/**
+ * Utility functions for working with resource bundles.
+ * Provides reusable logic for bundle detection, parsing, and component extraction.
+ * @public
+ */
+export class BundleUtils {
+    /**
+     * Checks if the given object appears to be a bundle file by examining its structure.
+     * This is a lightweight check that doesn't perform full validation.
+     * @param data - The data to check
+     * @returns True if the data appears to be a bundle structure
+     * @public
+     */
+    static isBundleFile(data) {
+        return bundleConverter.convert(data).isSuccess();
+    }
+    /**
+     * Extracts and validates components from a bundle for reuse.
+     * Performs full validation of the bundle structure and creates typed components.
+     * @param bundleData - The raw bundle data to extract components from
+     * @returns Success with bundle components if valid, Failure with error message otherwise
+     * @public
+     */
+    static extractBundleComponents(bundleData) {
+        return bundleConverter
+            .convert(bundleData)
+            .withErrorFormat((err) => `Invalid bundle structure: ${err}`)
+            .onSuccess((bundle) => {
+            return SystemConfiguration.create(bundle.config)
+                .withErrorFormat((err) => `Invalid system configuration in bundle: ${err}`)
+                .onSuccess((systemConfiguration) => {
+                return succeed({
+                    systemConfiguration,
+                    compiledCollection: bundle.compiledCollection,
+                    metadata: bundle.metadata
+                });
+            });
+        });
+    }
+    /**
+     * Extracts just the metadata from potential bundle data without full validation.
+     * Useful for displaying bundle information without processing the entire bundle.
+     * @param data - The data to extract metadata from
+     * @returns Success with metadata if found and valid, Failure otherwise
+     * @public
+     */
+    static extractBundleMetadata(data) {
+        return bundleConverter
+            .convert(data)
+            .onSuccess((bundle) => {
+            return succeed(bundle.metadata);
+        })
+            .withErrorFormat((err) => {
+            return `Not a bundle file: ${err}`;
+        });
+    }
+    /**
+     * Parses bundle data from a JSON string.
+     * Convenience method that combines JSON parsing with bundle component extraction.
+     * @param jsonString - The JSON string containing bundle data
+     * @returns Success with bundle components if valid, Failure with error message otherwise
+     * @public
+     */
+    static parseBundleFromJson(jsonString) {
+        try {
+            const data = JSON.parse(jsonString);
+            return BundleUtils.extractBundleComponents(data);
+        }
+        catch (error) {
+            /* c8 ignore next 1 - defense in depth */
+            return fail(`Failed to parse JSON: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    /**
+     * Checks if a file name suggests it might be a bundle file.
+     * This is a heuristic check based on file naming conventions.
+     * @param fileName - The file name to check
+     * @returns True if the file name suggests a bundle file
+     * @public
+     */
+    static isBundleFileName(fileName) {
+        const lowerName = fileName.toLowerCase();
+        return (lowerName.endsWith('.bundle.json') ||
+            lowerName.endsWith('-bundle.json') ||
+            lowerName.endsWith('_bundle.json') ||
+            (lowerName.includes('bundle') && lowerName.endsWith('.json')));
+    }
+}
+//# sourceMappingURL=bundleUtils.js.map

package/dist/packlets/bundle/convert.js

@@ -0,0 +1,75 @@
+/*
+ * 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 { Converters } from '@fgv/ts-utils';
+import { Converters as JsonConverters } from '@fgv/ts-json-base';
+import { Convert as ConfigConvert } from '../config';
+import { Compiled as ResourceJsonCompiled } from '../resource-json';
+/**
+ * `Converter` for a {@link Bundle.IBundleMetadata | bundle metadata} object.
+ * @public
+ */
+export const bundleMetadata = Converters.strictObject({
+    dateBuilt: Converters.string,
+    checksum: Converters.string,
+    version: Converters.string.optional(),
+    description: Converters.string.optional()
+});
+/**
+ * `Converter` for {@link Bundle.IBundleExportMetadata | bundle export metadata}.
+ * @public
+ */
+export const bundleExportMetadata = Converters.strictObject({
+    exportedAt: Converters.string,
+    exportedFrom: Converters.string,
+    type: Converters.string,
+    filterContext: JsonConverters.jsonObject.optional()
+});
+/**
+ * `Converter` for a {@link Bundle.IBundle | bundle} object.
+ * @public
+ */
+export const bundle = Converters.strictObject({
+    metadata: bundleMetadata,
+    config: ConfigConvert.systemConfiguration,
+    compiledCollection: ResourceJsonCompiled.Convert.compiledResourceCollection,
+    exportMetadata: bundleExportMetadata.optional()
+});
+/**
+ * `Converter` for {@link Bundle.IBundleCreateParams | bundle creation parameters}.
+ * @public
+ */
+export const bundleCreateParams = Converters.strictObject({
+    version: Converters.string.optional(),
+    description: Converters.string.optional(),
+    dateBuilt: Converters.string.optional()
+});
+/**
+ * Lightweight converter for bundle structure validation without full processing.
+ * Useful for detecting bundle files without the overhead of full validation.
+ * @public
+ */
+export const bundleStructure = Converters.strictObject({
+    metadata: bundleMetadata,
+    config: JsonConverters.jsonValue,
+    compiledCollection: JsonConverters.jsonValue
+});
+//# sourceMappingURL=convert.js.map