@fgv/ts-res 5.0.0-2 → 5.0.0-21

package/dist/tsdoc-metadata.json

@@ -5,7 +5,7 @@
   "toolPackages": [
     {
       "packageName": "@microsoft/api-extractor",
-      "packageVersion": "7.52.8"
+      "packageVersion": "7.52.10"
     }
   ]
 }

package/lib/index.d.ts

@@ -1,3 +1,4 @@
+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';
@@ -9,7 +10,15 @@ 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';
-export * from './packlets/common';
-export { Conditions, Config, Context, Decisions, Import, QualifierTypes, Qualifiers, ResourceJson, Resources, ResourceTypes, Runtime };
+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 { 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, ZipArchive };
 //# sourceMappingURL=index.d.ts.map

package/lib/index.js

@@ -57,7 +57,9 @@ 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.ResourceTypes = exports.Resources = exports.ResourceJson = exports.Qualifiers = exports.QualifierTypes = exports.Import = exports.Decisions = exports.Context = exports.Config = exports.Conditions = 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"));
 exports.QualifierTypes = QualifierTypes;
 const Qualifiers = __importStar(require("./packlets/qualifiers"));
@@ -80,6 +82,27 @@ 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);
-__exportStar(require("./packlets/common"), exports);
+const conditions_1 = require("./packlets/conditions");
+Object.defineProperty(exports, "Condition", { enumerable: true, get: function () { return conditions_1.Condition; } });
+Object.defineProperty(exports, "ConditionSet", { enumerable: true, get: function () { return conditions_1.ConditionSet; } });
+const decisions_1 = require("./packlets/decisions");
+Object.defineProperty(exports, "Decision", { enumerable: true, get: function () { return decisions_1.Decision; } });
+const qualifier_types_1 = require("./packlets/qualifier-types");
+Object.defineProperty(exports, "QualifierType", { enumerable: true, get: function () { return qualifier_types_1.QualifierType; } });
+const qualifiers_1 = require("./packlets/qualifiers");
+Object.defineProperty(exports, "Qualifier", { enumerable: true, get: function () { return qualifiers_1.Qualifier; } });
+const resource_types_1 = require("./packlets/resource-types");
+Object.defineProperty(exports, "ResourceType", { enumerable: true, get: function () { return resource_types_1.ResourceType; } });
+const resources_1 = require("./packlets/resources");
+Object.defineProperty(exports, "Resource", { enumerable: true, get: function () { return resources_1.Resource; } });
+Object.defineProperty(exports, "ResourceCandidate", { enumerable: true, get: function () { return resources_1.ResourceCandidate; } });
+Object.defineProperty(exports, "ResourceManagerBuilder", { enumerable: true, get: function () { return resources_1.ResourceManagerBuilder; } });
+const runtime_1 = require("./packlets/runtime");
+Object.defineProperty(exports, "ResourceResolver", { enumerable: true, get: function () { return runtime_1.ResourceResolver; } });
+const bundle_1 = require("./packlets/bundle");
+Object.defineProperty(exports, "BundleBuilder", { enumerable: true, get: function () { return bundle_1.BundleBuilder; } });
+Object.defineProperty(exports, "BundleLoader", { enumerable: true, get: function () { return bundle_1.BundleLoader; } });
 //# sourceMappingURL=index.js.map

package/lib/packlets/bundle/bundleBuilder.d.ts

@@ -0,0 +1,41 @@
+import { Result } from '@fgv/ts-utils';
+import { ResourceManagerBuilder } from '../resources';
+import { SystemConfiguration, PredefinedSystemConfiguration } from '../config';
+import { IBundle, IBundleCreateParams } from './model';
+/**
+ * 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 declare 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: ResourceManagerBuilder, systemConfig: SystemConfiguration, params?: IBundleCreateParams): Result<IBundle>;
+    /**
+     * 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: ResourceManagerBuilder, configName: PredefinedSystemConfiguration, params?: IBundleCreateParams): Result<IBundle>;
+    /**
+     * 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
+     */
+    private static _generateChecksum;
+}
+//# sourceMappingURL=bundleBuilder.d.ts.map

package/lib/packlets/bundle/bundleBuilder.js

@@ -0,0 +1,134 @@
+"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.BundleBuilder = void 0;
+const ts_utils_1 = require("@fgv/ts-utils");
+const config_1 = require("../config");
+const bundleNormalizer_1 = require("./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
+ */
+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 ts_utils_1.Hash.Crc32Normalizer();
+        const builderToUse = params.normalize === true
+            ? bundleNormalizer_1.BundleNormalizer.normalize(builder, systemConfig)
+            : /* c8 ignore next 1 - is tested but coverage gets confused */
+                (0, ts_utils_1.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 (0, ts_utils_1.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 ts_utils_1.Hash.Crc32Normalizer();
+        // Determine which builder to use based on normalization setting
+        const builderToUse = params.normalize
+            ? bundleNormalizer_1.BundleNormalizer.normalizeFromPredefined(builder, configName)
+            : (0, ts_utils_1.succeed)(builder);
+        return builderToUse.onSuccess((targetBuilder) => {
+            return (0, config_1.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 (0, ts_utils_1.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);
+    }
+}
+exports.BundleBuilder = BundleBuilder;
+//# sourceMappingURL=bundleBuilder.js.map

package/lib/packlets/bundle/bundleLoader.d.ts

@@ -0,0 +1,72 @@
+import { Result, Hash } from '@fgv/ts-utils';
+import { IResourceManager } from '../runtime';
+import { IBundle } from './model';
+/**
+ * Parameters for creating a BundleLoader.
+ * @public
+ */
+export interface IBundleLoaderCreateParams {
+    /**
+     * The bundle to load.
+     */
+    bundle: IBundle;
+    /**
+     * Whether to skip checksum verification during loading.
+     * Default is false - checksum verification is performed.
+     */
+    skipChecksumVerification?: boolean;
+    /**
+     * Optional hash normalizer for verifying checksums. If not provided,
+     * a CRC32 normalizer will be used for browser compatibility.
+     * Must match the normalizer used during bundle creation.
+     */
+    hashNormalizer?: Hash.HashingNormalizer;
+}
+/**
+ * Loader for creating an IResourceManager from a resource bundle.
+ * Handles integrity verification and reconstruction of the runtime resource manager.
+ * @public
+ */
+export declare 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: IBundleLoaderCreateParams): Result<IResourceManager>;
+    /**
+     * 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
+     */
+    private static _verifyBundleIntegrity;
+    /**
+     * 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
+     */
+    private static _generateChecksum;
+    /**
+     * 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
+     */
+    private static _createSystemConfiguration;
+    /**
+     * 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
+     */
+    private static _createCompiledResourceCollection;
+}
+//# sourceMappingURL=bundleLoader.d.ts.map

package/lib/packlets/bundle/bundleLoader.js

@@ -0,0 +1,105 @@
+"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.BundleLoader = void 0;
+const ts_utils_1 = require("@fgv/ts-utils");
+const runtime_1 = require("../runtime");
+const config_1 = require("../config");
+/**
+ * Loader for creating an IResourceManager from a resource bundle.
+ * Handles integrity verification and reconstruction of the runtime resource manager.
+ * @public
+ */
+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 ts_utils_1.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 (0, ts_utils_1.succeed)(true);
+        }
+        return BundleLoader._generateChecksum(bundle.compiledCollection, hashNormalizer).onSuccess((calculatedChecksum) => {
+            if (calculatedChecksum !== bundle.metadata.checksum) {
+                return (0, ts_utils_1.fail)(`Bundle integrity verification failed: expected checksum ${bundle.metadata.checksum}, got ${calculatedChecksum}`);
+            }
+            return (0, ts_utils_1.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 config_1.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 runtime_1.CompiledResourceCollection.create({
+            compiledCollection: bundle.compiledCollection,
+            qualifierTypes,
+            resourceTypes
+        });
+    }
+}
+exports.BundleLoader = BundleLoader;
+//# sourceMappingURL=bundleLoader.js.map

package/lib/packlets/bundle/bundleNormalizer.d.ts

@@ -0,0 +1,73 @@
+import { Result } from '@fgv/ts-utils';
+import { ResourceManagerBuilder } from '../resources';
+import { SystemConfiguration, PredefinedSystemConfiguration } from '../config';
+/**
+ * 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 declare 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: ResourceManagerBuilder, systemConfig: SystemConfiguration): Result<ResourceManagerBuilder>;
+    /**
+     * 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: ResourceManagerBuilder, configName: PredefinedSystemConfiguration): Result<ResourceManagerBuilder>;
+    /**
+     * 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
+     */
+    private static _normalizeConditions;
+    /**
+     * 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
+     */
+    private static _normalizeConditionSets;
+    /**
+     * 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
+     */
+    private static _normalizeCandidates;
+    /**
+     * 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
+     */
+    private static _addNormalizedResources;
+}
+//# sourceMappingURL=bundleNormalizer.d.ts.map

package/lib/packlets/bundle/bundleNormalizer.js

@@ -0,0 +1,142 @@
+"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.BundleNormalizer = void 0;
+const ts_utils_1 = require("@fgv/ts-utils");
+const resources_1 = require("../resources");
+const resources_2 = require("../resources");
+const conditions_1 = require("../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
+ */
+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 resources_1.ResourceManagerBuilder.create({
+            qualifiers: systemConfig.qualifiers,
+            resourceTypes: systemConfig.resourceTypes
+        }).onSuccess((normalizedBuilder) => {
+            return BundleNormalizer._addNormalizedResources(originalBuilder, normalizedBuilder).onSuccess(() => (0, ts_utils_1.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 resources_1.ResourceManagerBuilder.createPredefined(configName).onSuccess((normalizedBuilder) => {
+            return BundleNormalizer._addNormalizedResources(originalBuilder, normalizedBuilder).onSuccess(() => (0, ts_utils_1.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(conditions_1.Condition.compare);
+        const errors = new ts_utils_1.MessageAggregator();
+        for (const condition of conditions) {
+            const looseDecl = condition.toLooseConditionDecl();
+            normalizedBuilder.addCondition(looseDecl).aggregateError(errors);
+        }
+        return errors.returnOrReport((0, ts_utils_1.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(conditions_1.ConditionSet.compare);
+        const errors = new ts_utils_1.MessageAggregator();
+        for (const conditionSet of conditionSets) {
+            const conditions = conditionSet.toConditionSetArrayDecl();
+            normalizedBuilder.addConditionSet(conditions).aggregateError(errors);
+        }
+        return errors.returnOrReport((0, ts_utils_1.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 : resources_2.ResourceCandidate.compare(c1, c2);
+        });
+        const errors = new ts_utils_1.MessageAggregator();
+        for (const candidate of candidates) {
+            const decl = candidate.toLooseResourceCandidateDecl();
+            normalizedBuilder.addLooseCandidate(decl).aggregateError(errors);
+        }
+        return errors.returnOrReport((0, ts_utils_1.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));
+    }
+}
+exports.BundleNormalizer = BundleNormalizer;
+//# sourceMappingURL=bundleNormalizer.js.map