@fgv/ts-res 4.5.0-3 → 5.0.0-10

package/lib/packlets/resources/resourceManagerBuilder.js

@@ -0,0 +1,893 @@
+"use strict";
+/*
+ * Copyright (c) 2025 Erik Fortune
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ResourceManagerBuilder = void 0;
+const ts_utils_1 = require("@fgv/ts-utils");
+const ts_json_base_1 = require("@fgv/ts-json-base");
+const conditions_1 = require("../conditions");
+const decisions_1 = require("../decisions");
+const common_1 = require("../common");
+const runtime_1 = require("../runtime");
+const resourceBuilder_1 = require("./resourceBuilder");
+const resource_1 = require("./resource");
+const ResourceJson = __importStar(require("../resource-json"));
+const Context = __importStar(require("../context"));
+const Config = __importStar(require("../config"));
+const ts_json_1 = require("@fgv/ts-json");
+/**
+ * Builder for a collection of {@link Resources.Resource | resources}. Collects
+ * {@link Resources.ResourceCandidate | candidates} for each resource into a
+ * {@link Resources.ResourceBuilder | ResourceBuilder} per resource, validates them against each other,
+ * and builds a collection of {@link Resources.Resource | resources} once all candidates are collected.
+ * @public
+ */
+class ResourceManagerBuilder {
+    /**
+     * A {@link Conditions.ConditionCollector | ConditionCollector} which
+     * contains the {@link Conditions.Condition | conditions} used so far by
+     * the {@link Resources.ResourceCandidate | resource candidates} in this manager.
+     */
+    get conditions() {
+        return this._conditions;
+    }
+    /**
+     * A {@link Conditions.ConditionSetCollector | ConditionSetCollector} which
+     * contains the {@link Conditions.ConditionSet | condition sets} used so far by
+     * the {@link Resources.ResourceCandidate | resource candidates} in this manager.
+     */
+    get conditionSets() {
+        return this._conditionSets;
+    }
+    /**
+     * A {@link Decisions.AbstractDecisionCollector | AbstractDecisionCollector} which
+     * contains the {@link Decisions.Decision | abstract decisions} used so far by
+     * the {@link Resources.ResourceCandidate | resource candidates} in this manager.
+     */
+    get decisions() {
+        return this._decisions;
+    }
+    /**
+     * A read-only map of {@link Resources.ResourceBuilder | resource builders} used by the manager.
+     */
+    get resources() {
+        return this._resources;
+    }
+    /**
+     * The number of {@link Resources.Resource | resources} contained by the manager.
+     */
+    get size() {
+        return this._resources.size;
+    }
+    /**
+     * {@inheritdoc Runtime.IResourceManager.numResources}
+     */
+    get numResources() {
+        return this._resources.size;
+    }
+    /**
+     * {@inheritdoc Runtime.IResourceManager.numCandidates}
+     */
+    get numCandidates() {
+        if (this._numCandidates === undefined) {
+            this._numCandidates = this.getAllCandidates().length;
+        }
+        return this._numCandidates;
+    }
+    /**
+     * {@inheritdoc Runtime.IResourceManager.builtResources}
+     */
+    get builtResources() {
+        return this._performBuild().orThrow();
+    }
+    /**
+     * Constructor for a {@link Resources.ResourceManagerBuilder | ResourceManagerBuilder} object.
+     * @param params - Parameters to create a new {@link Resources.ResourceManagerBuilder | ResourceManagerBuilder}.
+     * @public
+     */
+    constructor(params) {
+        this.qualifiers = params.qualifiers;
+        this.resourceTypes = params.resourceTypes;
+        this._conditions = conditions_1.ConditionCollector.create({ qualifiers: params.qualifiers }).orThrow();
+        this._conditionSets = conditions_1.ConditionSetCollector.create({ conditions: this._conditions }).orThrow();
+        this._decisions = decisions_1.AbstractDecisionCollector.create({ conditionSets: this._conditionSets }).orThrow();
+        this._resources = new ts_utils_1.ValidatingResultMap({
+            converters: new ts_utils_1.Collections.KeyValueConverters({
+                key: common_1.Convert.resourceId,
+                /* c8 ignore next 2 - defense in depth against internal error */
+                value: (from) => from instanceof resourceBuilder_1.ResourceBuilder ? (0, ts_utils_1.succeed)(from) : (0, ts_utils_1.fail)('not a resource builder')
+            })
+        });
+        this._builtResources = new ts_utils_1.ValidatingResultMap({
+            converters: new ts_utils_1.Collections.KeyValueConverters({
+                key: common_1.Convert.resourceId,
+                /* c8 ignore next 1 - defense in depth against internal error */
+                value: (from) => (from instanceof resource_1.Resource ? (0, ts_utils_1.succeed)(from) : (0, ts_utils_1.fail)('not a resource'))
+            })
+        });
+        this._built = false;
+        this._cachedResourceTree = undefined;
+    }
+    /**
+     * Creates a new {@link Resources.ResourceManagerBuilder | ResourceManagerBuilder} object.
+     * @param params - Parameters to create a new {@link Resources.ResourceManagerBuilder | ResourceManagerBuilder}.
+     * @returns `Success` with the new {@link Resources.ResourceManagerBuilder | ResourceManagerBuilder} object if successful,
+     * or `Failure` with an error message if not.
+     * @public
+     */
+    static create(params) {
+        return (0, ts_utils_1.captureResult)(() => new ResourceManagerBuilder(params));
+    }
+    /**
+     * Creates a new {@link Resources.ResourceManagerBuilder | ResourceManagerBuilder} object from a predefined system configuration.
+     * @param name - The name of the predefined system configuration to use.
+     * @param qualifierDefaultValues - Optional default values for qualifiers.
+     * @returns `Success` with the new {@link Resources.ResourceManagerBuilder | ResourceManagerBuilder} object if successful,
+     * or `Failure` with an error message if not.
+     * @public
+     */
+    static createPredefined(name, qualifierDefaultValues) {
+        return Config.getPredefinedSystemConfiguration(name, 
+        /* c8 ignore next 1 - defense in depth */
+        qualifierDefaultValues ? { qualifierDefaultValues } : undefined).onSuccess((systemConfig) => {
+            return ResourceManagerBuilder.create({
+                qualifiers: systemConfig.qualifiers,
+                resourceTypes: systemConfig.resourceTypes
+            });
+        });
+    }
+    /**
+     * Creates a new {@link Resources.ResourceManagerBuilder | ResourceManagerBuilder} from a
+     * {@link ResourceJson.Compiled.ICompiledResourceCollection | compiled resource collection}.
+     * This method reconstructs an exactly equivalent builder where all qualifier, condition,
+     * condition set, and decision indices match the original compiled collection.
+     * @param compiledCollection - The compiled resource collection to reconstruct from.
+     * @param systemConfig - The system configuration containing qualifiers and resource types.
+     * @returns `Success` with the new manager if successful, or `Failure` with an error message if not.
+     * @public
+     */
+    static createFromCompiledResourceCollection(compiledCollection, systemConfig) {
+        // Create the base builder with system configuration
+        return ResourceManagerBuilder.create({
+            qualifiers: systemConfig.qualifiers,
+            resourceTypes: systemConfig.resourceTypes
+        }).onSuccess((builder) => {
+            // Reconstruct all entities in order to preserve indices
+            return ResourceManagerBuilder._reconstructConditions(builder, compiledCollection)
+                .onSuccess(() => ResourceManagerBuilder._reconstructConditionSets(builder, compiledCollection))
+                .onSuccess(() => ResourceManagerBuilder._reconstructDecisions(builder, compiledCollection))
+                .onSuccess(() => ResourceManagerBuilder._reconstructResources(builder, compiledCollection))
+                .onSuccess(() => (0, ts_utils_1.succeed)(builder));
+        });
+    }
+    /**
+     * Given a {@link ResourceJson.Json.ILooseResourceCandidateDecl | resource candidate declaration}, builds and adds
+     * a {@link Resources.ResourceCandidate | candidate} to the manager.
+     * @param candidate - The {@link Resources.ResourceCandidate | candidate} to add.
+     * @returns `Success` with the candidate if successful, or `Failure` with an error message if not.
+     * @public
+     */
+    addLooseCandidate(decl) {
+        const { value: id, message } = common_1.Validate.toResourceId(decl.id);
+        if (message !== undefined) {
+            return (0, ts_utils_1.failWithDetail)(`${id}: invalid id - ${message}`, 'failure');
+        }
+        const builderResult = this._resources.getOrAdd(id, () => resourceBuilder_1.ResourceBuilder.create({
+            id,
+            resourceTypes: this.resourceTypes,
+            conditionSets: this._conditionSets,
+            decisions: this._decisions
+        }));
+        /* c8 ignore next 6 - defense in depth against internal error */
+        if (builderResult.isFailure()) {
+            return (0, ts_utils_1.failWithDetail)(`${id}: unable to get or add resource\n${builderResult.message}`, builderResult.detail);
+        }
+        return builderResult.value.addLooseCandidate(decl).onSuccess((c, d) => {
+            this._builtResources.delete(id);
+            this._built = false;
+            this._numCandidates = undefined;
+            this._cachedResourceTree = undefined;
+            return (0, ts_utils_1.succeedWithDetail)(c, d);
+        });
+    }
+    addResource(decl) {
+        var _a;
+        const { value: id, message } = common_1.Validate.toResourceId(decl.id);
+        if (message !== undefined) {
+            return (0, ts_utils_1.failWithDetail)(`${id}: invalid id - ${message}`, 'failure');
+        }
+        const { value: builder, message: getOrAddMessage, detail } = this._resources.getOrAdd(id, () => resourceBuilder_1.ResourceBuilder.create({
+            id,
+            typeName: decl.resourceTypeName,
+            resourceTypes: this.resourceTypes,
+            conditionSets: this._conditionSets,
+            decisions: this._decisions
+        }));
+        /* c8 ignore next 3 - defense in depth against internal error */
+        if (getOrAddMessage !== undefined) {
+            return (0, ts_utils_1.failWithDetail)(`${id}: unable to get or add resource\n${getOrAddMessage}`, detail);
+        }
+        if (detail === 'exists') {
+            const { message } = builder.setResourceType(decl.resourceTypeName);
+            if (message !== undefined) {
+                return (0, ts_utils_1.failWithDetail)(`${id}: unable to set resource type\n${message}`, 'type-mismatch');
+            }
+        }
+        const candidates = (_a = decl.candidates) !== null && _a !== void 0 ? _a : [];
+        return (0, ts_utils_1.mapResults)(candidates.map((c) => builder.addChildCandidate(c)))
+            .onSuccess(() => {
+            return (0, ts_utils_1.succeed)(builder);
+        })
+            .withDetail('failure', detail);
+    }
+    /**
+     * Adds a condition to the manager.
+     * @param decl - The condition declaration to add.
+     * @returns `Success` with the condition if successful, or `Failure` with an error message if not.
+     * @public
+     */
+    addCondition(decl) {
+        return conditions_1.Convert.validatedConditionDecl
+            .convert(decl, { qualifiers: this.qualifiers })
+            .onSuccess((validated) => {
+            return conditions_1.Condition.getKeyForDecl(validated).onSuccess((key) => {
+                return this._conditions.validating.getOrAdd(key, () => conditions_1.Condition.create(validated));
+            });
+        });
+    }
+    /**
+     * Adds a condition set to the manager.
+     * @param decl - The condition set declaration to add.
+     * @returns `Success` with the condition set if successful, or `Failure` with an error message if not.
+     * @public
+     */
+    addConditionSet(conditions) {
+        const decl = { conditions: [...conditions] };
+        return conditions_1.Convert.validatedConditionSetDecl
+            .convert(decl, { conditions: this._conditions })
+            .onSuccess((validated) => {
+            return conditions_1.ConditionSet.getKeyForDecl(validated).onSuccess((key) => {
+                return this._conditionSets.validating.getOrAdd(key, () => conditions_1.ConditionSet.create(validated));
+            });
+        });
+    }
+    /**
+     * Gets a read-only array of all {@link Resources.ResourceBuilder | resource builders} present in the manager.
+     * @returns `Success` with the {@link Resources.ResourceBuilder | resource builder} if successful,
+     * or `Failure` with an error message if not.
+     */
+    getAllResources() {
+        return Array.from(this._resources.values()).sort((a, b) => a.id.localeCompare(b.id));
+    }
+    /**
+     * Gets a read-only array of all {@link Resources.ResourceCandidate | resource candidates} present in the manager.
+     */
+    getAllCandidates() {
+        return this.getAllResources().flatMap((r) => r.candidates);
+    }
+    /**
+     * Gets an individual {@link Resources.Resource | built resource} from the manager.
+     * @param id - The {@link ResourceId | id} of the resource to get.
+     * @returns `Success` with the resource if successful, or `Failure` with an error message if not.
+     * @public
+     */
+    getBuiltResource(id) {
+        return this._resources.validating
+            .get(id)
+            .onSuccess((builder) => this._builtResources.validating.getOrAdd(id, () => builder.build()));
+    }
+    /**
+     * Validates a context declaration against the qualifiers managed by this resource manager.
+     * @param context - The context declaration to validate
+     * @returns Success with the validated context if successful, Failure otherwise
+     * @public
+     */
+    /* c8 ignore next 5 - functional code path tested but coverage intermittently missed */
+    validateContext(context) {
+        return Context.Convert.validatedContextDecl.convert(context, {
+            qualifiers: this.qualifiers
+        });
+    }
+    /**
+     * Gets a read-only array of all {@link Resources.Resource | built resources} in the manager.
+     * @returns `Success` with an array of resources if successful, or `Failure` with an error message if not.
+     * @public
+     */
+    getAllBuiltResources() {
+        return this.build().onSuccess((manager) => (0, ts_utils_1.succeed)(Array.from(manager._builtResources.values()).sort((a, b) => a.id.localeCompare(b.id))));
+    }
+    /**
+     * Builds and returns a hierarchical tree representation of all resources managed by this builder.
+     * Resources are organized based on their dot-separated resource IDs (e.g., "app.messages.welcome"
+     * becomes a tree with "app" as root, "messages" as branch, and "welcome" as leaf).
+     *
+     * String-based validation is available through the `children.validating` property,
+     * allowing callers to use `tree.children.validating.getById(stringId)` for validated access.
+     *
+     * Uses lazy initialization with caching for performance.
+     * @returns Result containing the resource tree root, or failure if tree construction fails
+     * @public
+     */
+    getBuiltResourceTree() {
+        // Ensure resources are built first
+        return this.build().onSuccess((manager) => {
+            if (manager._cachedResourceTree) {
+                return (0, ts_utils_1.succeed)(manager._cachedResourceTree);
+            }
+            // Convert all built resources to [ResourceId, Resource] pairs
+            const resources = [];
+            for (const [id, resource] of manager._builtResources.entries()) {
+                resources.push([id, resource]);
+            }
+            // Create the resource tree with lazy initialization
+            return runtime_1.ResourceTree.ReadOnlyResourceTreeRoot.create(resources).onSuccess((tree) => {
+                manager._cachedResourceTree = tree;
+                return (0, ts_utils_1.succeed)(tree);
+            });
+        });
+    }
+    /**
+     * Gets a read-only array of all {@link Resources.Resource | built resources} in the manager.
+     * @returns `Success` with an array of resources if successful, or `Failure` with an error message if not.
+     * @public
+     */
+    getAllBuiltCandidates() {
+        return this.getAllBuiltResources().onSuccess((built) => (0, ts_utils_1.succeed)(built.flatMap((r) => r.candidates)));
+    }
+    /**
+     * Internal helper method that performs the actual building of resources.
+     * @returns `Success` with the built resources if all resources were built successfully, `Failure` otherwise.
+     * @internal
+     */
+    _performBuild() {
+        if (this._built) {
+            return (0, ts_utils_1.succeed)(this._builtResources);
+        }
+        const errors = new ts_utils_1.MessageAggregator();
+        this._resources.forEach((r, id) => {
+            this._builtResources.getOrAdd(id, () => r.build()).aggregateError(errors);
+        });
+        /* c8 ignore next 3 - defense in depth against internal error */
+        if (errors.hasMessages) {
+            return (0, ts_utils_1.fail)(`build failed: ${errors.toString()}`);
+        }
+        this._built = true;
+        return (0, ts_utils_1.succeed)(this._builtResources);
+    }
+    /**
+     * Builds the {@link Resources.Resource | resources} from the collected {@link Resources.ResourceCandidate | candidates}.
+     * @returns `Success` with the {@link Resources.ResourceManagerBuilder | ResourceManagerBuilder} object if successful,
+     * or `Failure` with an error message if not.
+     * @public
+     */
+    build() {
+        return this._performBuild().onSuccess(() => (0, ts_utils_1.succeed)(this));
+    }
+    /**
+     * Gets a read-only array of all {@link Resources.ResourceCandidate | resource candidates} that can match the supplied context.
+     * @param context - The {@link Context.IValidatedContextDecl | context} to match against.
+     * @param options - {@link Context.IContextMatchOptions | options} for the context match.
+     * @returns A read-only array of {@link Resources.ResourceCandidate | candidates} that can match the context.
+     * @public
+     */
+    getCandidatesForContext(context, options) {
+        return this.getAllCandidates().filter((candidate) => candidate.canMatchPartialContext(context, options));
+    }
+    /**
+     * Gets a read-only array of all {@link Resources.ResourceBuilder | resource builders} that have at least one candidate
+     * that can match the supplied context.
+     * @param context - The {@link Context.IValidatedContextDecl | context} to match against.
+     * @param options - {@link Context.IContextMatchOptions | options} for the context match.
+     * @returns A read-only array of {@link Resources.ResourceBuilder | resource builders} with matching candidates.
+     * @public
+     */
+    getResourcesForContext(context, options) {
+        return this.getAllResources().filter((resource) => resource.getCandidatesForContext(context, options).length > 0);
+    }
+    /**
+     * Gets a read-only array of all {@link Resources.ResourceCandidate | built resource candidates} that can match the supplied context.
+     * @param context - The {@link Context.IValidatedContextDecl | context} to match against.
+     * @param options - {@link Context.IContextMatchOptions | options} for the context match.
+     * @returns `Success` with an array of {@link Resources.ResourceCandidate | candidates} if successful, or `Failure` with an error message if not.
+     * @public
+     */
+    getBuiltCandidatesForContext(context, options) {
+        return this.getAllBuiltCandidates().onSuccess((candidates) => (0, ts_utils_1.succeed)(candidates.filter((candidate) => candidate.canMatchPartialContext(context, options))));
+    }
+    /**
+     * Gets a read-only array of all {@link Resources.Resource | built resources} that have at least one candidate
+     * that can match the supplied context.
+     * @param context - The {@link Context.IValidatedContextDecl | context} to match against.
+     * @param options - {@link Context.IContextMatchOptions | options} for the context match.
+     * @returns `Success` with an array of {@link Resources.Resource | resources} if successful, or `Failure` with an error message if not.
+     * @public
+     */
+    getBuiltResourcesForContext(context, options) {
+        return this.getAllBuiltResources().onSuccess((resources) => (0, ts_utils_1.succeed)(resources.filter((resource) => resource.getCandidatesForContext(context, options).length > 0)));
+    }
+    /**
+     * Gets a compiled resource collection from the current state of the resource manager builder.
+     * This method generates an optimized, index-based representation of all resources, conditions,
+     * and decisions that can be used for serialization or efficient runtime processing.
+     * @param options - Optional compilation options controlling the output format.
+     * @returns Success with the compiled resource collection if successful, Failure otherwise.
+     * @public
+     */
+    getCompiledResourceCollection(options) {
+        // Build resources first to ensure all data is available
+        const buildResult = this._performBuild();
+        if (buildResult.isFailure()) {
+            return (0, ts_utils_1.fail)(`Failed to build resources: ${buildResult.message}`);
+        }
+        // Generate compiled data from internal collections using the new toCompiled methods
+        // Note: All objects have a defined index property due to the collector pattern - indices are assigned during collection building
+        const compiledData = {
+            qualifierTypes: Array.from(this.qualifiers.qualifierTypes.values()).map((qt) => ({
+                name: qt.name
+            })),
+            qualifiers: Array.from(this.qualifiers.values()).map((q) => ({
+                name: q.name,
+                type: q.type.index,
+                defaultPriority: q.defaultPriority
+            })),
+            resourceTypes: Array.from(this.resourceTypes.values()).map((rt) => ({
+                name: rt.key
+            })),
+            conditions: Array.from(this._conditions.values()).map((c) => c.toCompiled(options)),
+            conditionSets: Array.from(this._conditionSets.values()).map((cs) => cs.toCompiled(options)),
+            decisions: Array.from(this._decisions.values()).map((d) => d.toCompiled(options)),
+            resources: Array.from(this._builtResources.values()).map((r) => r.toCompiled(options))
+        };
+        // Apply validation through the converter
+        return ResourceJson.Compiled.Convert.compiledResourceCollection.convert(compiledData);
+    }
+    /**
+     * Gets a resource collection declaration containing all built resources in a flat array structure.
+     * This method returns all built resources as an {@link ResourceJson.Normalized.IResourceCollectionDecl | IResourceCollectionDecl}
+     * that can be used for serialization, export, or re-import. Resources are sorted by ID for consistent ordering.
+     * @param options - Optional {@link Resources.IResourceDeclarationOptions | declaration options} controlling the output format.
+     * If `options.normalized` is `true`, applies hash-based normalization for additional consistency guarantees.
+     * @returns Success with the resource collection declaration if successful, Failure otherwise.
+     * @public
+     */
+    getResourceCollectionDecl(options) {
+        return this._performBuild().onSuccess(() => {
+            // Get all built resources and convert to loose resource declarations
+            const resources = Array.from(this._builtResources.values()).map((resource) => resource.toLooseResourceDecl(options));
+            // Sort resources by ID for consistent ordering
+            resources.sort((a, b) => a.id.localeCompare(b.id));
+            // Create the collection declaration structure
+            const collectionData = {
+                resources
+            };
+            // Convert and validate using the normalized converter
+            return ResourceJson.Convert.resourceCollectionDecl
+                .convert(collectionData)
+                .onSuccess((compiledCollection) => {
+                // Apply hash-based normalization only if requested
+                if ((options === null || options === void 0 ? void 0 : options.normalized) === true) {
+                    const normalizer = new ts_utils_1.Hash.Crc32Normalizer();
+                    return normalizer
+                        .normalize(compiledCollection)
+                        .withErrorFormat((e) => `Failed to normalize resource collection: ${e}`);
+                }
+                return (0, ts_utils_1.succeed)(compiledCollection);
+            });
+        });
+    }
+    /**
+     * Creates a filtered clone of this ResourceManagerBuilder using the specified context.
+     * This is a convenience method that creates a new ResourceManagerBuilder with the same
+     * configuration but filtered to include only candidates that match the provided context.
+     * If candidates are provided for editing, they will be applied with collision detection.
+     * @param options - Options for the cloning operation, including the strongly-typed filterForContext property and optional candidates for edits.
+     * @returns A Result containing the new filtered ResourceManagerBuilder.
+     * @public
+     */
+    /* c8 ignore next 21 - functional code path tested but coverage intermittently missed */
+    clone(options) {
+        return this.getResourceCollectionDecl(options).onSuccess((collection) => {
+            return ResourceManagerBuilder.create({
+                qualifiers: this.qualifiers,
+                resourceTypes: this.resourceTypes
+            }).onSuccess((newManager) => {
+                // Check if we have candidates to apply as edits
+                const editCandidates = (options === null || options === void 0 ? void 0 : options.candidates) || [];
+                const candidatesByResourceResult = editCandidates.length > 0
+                    ? ResourceManagerBuilder._createCandidatesByResourceMap(editCandidates)
+                    : (0, ts_utils_1.succeed)(new Map());
+                return candidatesByResourceResult.onSuccess((candidatesByResource) => {
+                    // Track which resource IDs have been processed from the original collection
+                    const processedResourceIds = new Set();
+                    // Add each resource from the filtered collection to the new manager
+                    if (collection.resources) {
+                        for (const resourceDecl of collection.resources) {
+                            processedResourceIds.add(resourceDecl.id);
+                            // Apply edits if there are candidates for this resource
+                            const editedDeclResult = ResourceManagerBuilder._applyEditsToResourceDeclaration(resourceDecl, candidatesByResource, this._conditions);
+                            if (editedDeclResult.isFailure()) {
+                                return (0, ts_utils_1.fail)(`${resourceDecl.id}: Failed to apply edits: ${editedDeclResult.message}`);
+                            }
+                            const addResult = newManager.addResource(editedDeclResult.value);
+                            /* c8 ignore next 5 - edge case (nearly?) impossible to reproduce */
+                            if (addResult.isFailure()) {
+                                return (0, ts_utils_1.fail)(`${resourceDecl.id}: Failed to add resource to cloned manager: ${addResult.message}`);
+                            }
+                        }
+                    }
+                    // Handle any remaining candidates that target new resources not in the original collection
+                    const errors = new ts_utils_1.MessageAggregator();
+                    for (const [resourceId, candidates] of candidatesByResource) {
+                        if (!processedResourceIds.has(resourceId)) {
+                            // Create a new resource declaration for candidates targeting a new resource ID
+                            ResourceManagerBuilder._createResourceDeclFromCandidates(resourceId, candidates, this._conditions)
+                                .withErrorFormat((e) => `${resourceId}: Failed to create new resource from candidates: ${e}`)
+                                .onSuccess((newResourceDecl) => {
+                                return newManager
+                                    .addResource(newResourceDecl)
+                                    .withErrorFormat((e) => `${resourceId}: Failed to add new resource to cloned manager: ${e}`);
+                            })
+                                .aggregateError(errors);
+                        }
+                    }
+                    return errors.returnOrReport((0, ts_utils_1.succeed)(newManager));
+                });
+            });
+        });
+    }
+    /**
+     * Creates a resource ID keyed map from an array of loose resource candidate declarations.
+     * This enables efficient detection of edit collisions by grouping candidates by their target resource.
+     * @param candidates - Array of loose resource candidate declarations to organize
+     * @returns A Result containing a Map where keys are validated ResourceIds and values are arrays of candidates for that resource
+     * @internal
+     */
+    static _createCandidatesByResourceMap(candidates) {
+        const candidatesByResource = new Map();
+        for (const candidate of candidates) {
+            const { value: resourceId, message } = common_1.Validate.toResourceId(candidate.id);
+            if (message !== undefined) {
+                return (0, ts_utils_1.fail)(`Invalid resource ID "${candidate.id}": ${message}`);
+            }
+            const existingCandidates = candidatesByResource.get(resourceId);
+            if (existingCandidates) {
+                existingCandidates.push(candidate);
+            }
+            else {
+                candidatesByResource.set(resourceId, [candidate]);
+            }
+        }
+        return (0, ts_utils_1.succeed)(candidatesByResource);
+    }
+    /**
+     * Generates a proper ConditionSet token for collision detection using the existing ConditionSet.getKeyForDecl method.
+     * @param conditionSet - The condition set to generate a token for
+     * @param conditionCollector - The condition collector needed for validation context
+     * @returns A Result containing the ConditionSet token if successful, or failure if validation fails
+     * @internal
+     */
+    /**
+     * Applies candidate edits to a resource declaration, handling collisions using condition set tokens.
+     * If there's no collision, adds the candidate. If there's a collision, replaces the original candidate with the edit.
+     * @param resourceDecl - The original resource declaration to potentially modify
+     * @param candidatesByResource - Map of resource IDs to arrays of candidate edits
+     * @param conditionCollector - The condition collector needed for generating condition tokens
+     * @returns A Result containing the resource declaration to use (original or modified)
+     * @internal
+     */
+    static _applyEditsToResourceDeclaration(resourceDecl, candidatesByResource, conditionCollector) {
+        var _a, _b;
+        const { value: resourceId, message } = common_1.Validate.toResourceId(resourceDecl.id);
+        /* c8 ignore next 3 - defensive validation: resource IDs are validated when added to builder, but this protects against corrupted data */
+        if (message !== undefined) {
+            return (0, ts_utils_1.fail)(`Invalid resource ID "${resourceDecl.id}": ${message}`);
+        }
+        const editCandidates = candidatesByResource.get(resourceId);
+        if (!editCandidates || editCandidates.length === 0) {
+            return (0, ts_utils_1.succeed)(resourceDecl);
+        }
+        // Use Map approach: apply original candidates first, then replace with edits on collision
+        const candidatesByConditionKey = new Map();
+        /* c8 ignore next 1 - ?? is defense in depth */
+        const declCandidates = (_a = resourceDecl.candidates) !== null && _a !== void 0 ? _a : [];
+        // First, add all original candidates keyed by their condition set token
+        for (const candidate of declCandidates) {
+            const conditionTokenResult = conditions_1.ConditionSet.getKeyFromLooseDecl(candidate.conditions, conditionCollector);
+            /* c8 ignore next 5 - edge case or internal error (nearly?) impossible to reproduce */
+            if (conditionTokenResult.isFailure()) {
+                return (0, ts_utils_1.fail)(`Failed to generate condition token for original candidate: ${conditionTokenResult.message}`);
+            }
+            candidatesByConditionKey.set(conditionTokenResult.value, candidate);
+        }
+        // Then, apply edits (this replaces any colliding original candidates)
+        // Convert edit candidates (which have ids) to child candidates (without ids) for merging
+        for (const editCandidate of editCandidates) {
+            const conditionTokenResult = conditions_1.ConditionSet.getKeyFromLooseDecl(editCandidate.conditions, conditionCollector);
+            if (conditionTokenResult.isFailure()) {
+                return (0, ts_utils_1.fail)(`Failed to generate condition token for edit candidate: ${conditionTokenResult.message}`);
+            }
+            let editedJson = editCandidate.json;
+            const previousJson = (_b = candidatesByConditionKey.get(conditionTokenResult.value)) === null || _b === void 0 ? void 0 : _b.json;
+            if (previousJson && previousJson !== editedJson) {
+                editedJson = ts_json_1.JsonEditor.create({
+                    merge: {
+                        arrayMergeBehavior: 'replace',
+                        nullAsDelete: false
+                    }
+                })
+                    .onSuccess((editor) => {
+                    return editor.mergeObjectsInPlace({}, [previousJson, editedJson]);
+                })
+                    .orThrow();
+            }
+            const childCandidate = {
+                json: editedJson,
+                conditions: editCandidate.conditions,
+                isPartial: editCandidate.isPartial,
+                mergeMethod: editCandidate.mergeMethod
+            };
+            candidatesByConditionKey.set(conditionTokenResult.value, childCandidate);
+        }
+        // Extract the final merged candidate list
+        const mergedCandidates = Array.from(candidatesByConditionKey.values());
+        const modifiedDecl = Object.assign(Object.assign({}, resourceDecl), { candidates: mergedCandidates });
+        return (0, ts_utils_1.succeed)(modifiedDecl);
+    }
+    /**
+     * Creates a new resource declaration from an array of candidate declarations.
+     * This is used when cloning to create new resources that don't exist in the original manager.
+     * @param resourceId - The validated resource ID for the new resource
+     * @param candidates - Array of loose candidate declarations for the new resource
+     * @param conditionCollector - The condition collector for validation context
+     * @returns A Result containing the new resource declaration if successful, or failure if validation fails
+     * @internal
+     */
+    static _createResourceDeclFromCandidates(resourceId, candidates, conditionCollector) {
+        // Convert candidate declarations to child candidate declarations
+        const childCandidates = [];
+        // Ensure we have candidates
+        /* c8 ignore next 3 - defense in depth against internal error */
+        if (candidates.length === 0) {
+            return (0, ts_utils_1.fail)('Cannot create resource declaration from empty candidates array');
+        }
+        // Extract resourceTypeName from the first candidate (all candidates for the same resource should have the same type)
+        const resourceTypeName = candidates[0].resourceTypeName;
+        /* c8 ignore next 3 - defense in depth */
+        if (!resourceTypeName) {
+            return (0, ts_utils_1.fail)('resourceTypeName is required for new resource candidates');
+        }
+        for (const candidate of candidates) {
+            const childCandidate = {
+                json: candidate.json,
+                conditions: candidate.conditions,
+                isPartial: candidate.isPartial,
+                mergeMethod: candidate.mergeMethod
+            };
+            childCandidates.push(childCandidate);
+        }
+        // Create the new resource declaration
+        const newResourceDecl = {
+            id: resourceId,
+            candidates: childCandidates,
+            resourceTypeName
+        };
+        return (0, ts_utils_1.succeed)(newResourceDecl);
+    }
+    /**
+     * Reconstructs conditions from a compiled collection and adds them to the builder.
+     * @param builder - The builder to add conditions to.
+     * @param compiledCollection - The compiled collection containing conditions.
+     * @returns `Success` if all conditions were added successfully, `Failure` otherwise.
+     * @internal
+     */
+    static _reconstructConditions(builder, compiledCollection) {
+        const errors = new ts_utils_1.MessageAggregator();
+        for (const compiledCondition of compiledCollection.conditions) {
+            // Get the qualifier by index
+            const qualifierResult = builder.qualifiers.getAt(compiledCondition.qualifierIndex);
+            /* c8 ignore next 4 - edge case or internal error (nearly?) impossible to reproduce */
+            if (qualifierResult.isFailure()) {
+                qualifierResult.aggregateError(errors);
+                continue;
+            }
+            // Create condition declaration from compiled condition
+            const conditionDecl = {
+                qualifierName: qualifierResult.value.name,
+                operator: compiledCondition.operator,
+                value: compiledCondition.value,
+                priority: compiledCondition.priority,
+                scoreAsDefault: compiledCondition.scoreAsDefault
+            };
+            // Add condition to builder (it will get the next sequential index)
+            builder.addCondition(conditionDecl).aggregateError(errors);
+        }
+        return errors.returnOrReport((0, ts_utils_1.succeed)(true));
+    }
+    /**
+     * Reconstructs condition sets from a compiled collection and adds them to the builder.
+     * @param builder - The builder to add condition sets to.
+     * @param compiledCollection - The compiled collection containing condition sets.
+     * @returns `Success` if all condition sets were added successfully, `Failure` otherwise.
+     * @internal
+     */
+    static _reconstructConditionSets(builder, compiledCollection) {
+        const errors = new ts_utils_1.MessageAggregator();
+        for (const compiledConditionSet of compiledCollection.conditionSets) {
+            // Get conditions by their indices
+            const conditionResults = compiledConditionSet.conditions.map((idx) => builder._conditions.getAt(idx));
+            // Check for any failures
+            const failedIndex = conditionResults.findIndex((r) => r.isFailure());
+            /* c8 ignore next 4 - edge case or internal error (nearly?) impossible to reproduce */
+            if (failedIndex >= 0) {
+                conditionResults[failedIndex].aggregateError(errors);
+                continue;
+            }
+            // Create condition set from conditions (not declarations)
+            const conditions = conditionResults.map((r) => r.orThrow());
+            // Convert conditions to declarations for addConditionSet
+            const conditionDecls = conditions.map((c) => c.toLooseConditionDecl());
+            builder.addConditionSet(conditionDecls).aggregateError(errors);
+        }
+        return errors.returnOrReport((0, ts_utils_1.succeed)(true));
+    }
+    /**
+     * Reconstructs decisions from a compiled collection and adds them to the builder.
+     * @param builder - The builder to add decisions to.
+     * @param compiledCollection - The compiled collection containing decisions.
+     * @returns `Success` if all decisions were added successfully, `Failure` otherwise.
+     * @internal
+     */
+    static _reconstructDecisions(builder, compiledCollection) {
+        const errors = new ts_utils_1.MessageAggregator();
+        for (const compiledDecision of compiledCollection.decisions) {
+            // Get condition sets by their indices
+            const conditionSetResults = compiledDecision.conditionSets.map((idx) => builder._conditionSets.getAt(idx));
+            // Check for any failures
+            const failedIndex = conditionSetResults.findIndex((r) => r.isFailure());
+            if (failedIndex >= 0) {
+                conditionSetResults[failedIndex].aggregateError(errors);
+                continue;
+            }
+            // Get condition sets from successful results
+            const conditionSets = conditionSetResults.map((r) => r.orThrow());
+            // Create AbstractDecision from condition sets and add to collector
+            decisions_1.AbstractDecision.createAbstractDecision({ conditionSets })
+                .onSuccess((decision) => builder._decisions.getOrAdd(decision))
+                .aggregateError(errors);
+        }
+        return errors.returnOrReport((0, ts_utils_1.succeed)(true));
+    }
+    /**
+     * Reconstructs resources and their candidates from a compiled collection and adds them to the builder.
+     * @param builder - The builder to add resources to.
+     * @param compiledCollection - The compiled collection containing resources.
+     * @returns `Success` if all resources were added successfully, `Failure` otherwise.
+     * @internal
+     */
+    static _reconstructResources(builder, compiledCollection) {
+        const errors = new ts_utils_1.MessageAggregator();
+        for (const compiledResource of compiledCollection.resources) {
+            // Get the resource type by index
+            const resourceTypeResult = builder.resourceTypes.getAt(compiledResource.type);
+            /* c8 ignore next 4 - edge case or internal error (nearly?) impossible to reproduce */
+            if (resourceTypeResult.isFailure()) {
+                resourceTypeResult.aggregateError(errors);
+                continue;
+            }
+            // Get the decision by index
+            const decisionResult = builder._decisions.getAt(compiledResource.decision);
+            /* c8 ignore next 4 - edge case or internal error (nearly?) impossible to reproduce */
+            if (decisionResult.isFailure()) {
+                decisionResult.aggregateError(errors);
+                continue;
+            }
+            const decision = decisionResult.value;
+            const resourceType = resourceTypeResult.value;
+            // Create candidates from the decision's condition sets
+            ResourceManagerBuilder._createCandidatesFromDecision(compiledResource, decision, resourceType, builder).aggregateError(errors);
+        }
+        return errors.returnOrReport((0, ts_utils_1.succeed)(true));
+    }
+    /**
+     * Helper method to create candidates from a decision's condition sets.
+     * @param compiledResource - The compiled resource containing candidates.
+     * @param decision - The decision containing condition sets.
+     * @param resourceType - The resource type for the candidates.
+     * @param builder - The builder to add candidates to.
+     * @returns `Success` if all candidates were added successfully, `Failure` otherwise.
+     * @internal
+     */
+    static _createCandidatesFromDecision(compiledResource, decision, resourceType, builder) {
+        var _a;
+        const errors = new ts_utils_1.MessageAggregator();
+        // Match each candidate to its corresponding condition set
+        for (let i = 0; i < compiledResource.candidates.length; i++) {
+            const candidate = compiledResource.candidates[i];
+            // Build conditions from the corresponding condition set (if available)
+            let conditions;
+            if (i < decision.candidates.length) {
+                const decisionCandidate = decision.candidates[i];
+                conditions = {};
+                for (const condition of decisionCandidate.conditionSet.conditions) {
+                    conditions[condition.qualifier.name] = condition.value;
+                }
+                /* c8 ignore next 3 - defense in depth */
+                if (Object.keys(conditions).length === 0) {
+                    conditions = undefined;
+                }
+            }
+            // Convert json value to JsonObject, handling undefined case
+            /* c8 ignore next 1 - defense in depth */
+            const rawJson = (_a = candidate.json) !== null && _a !== void 0 ? _a : {};
+            ts_json_base_1.Converters.jsonObject
+                .convert(rawJson)
+                .onSuccess((json) => {
+                const candidateDecl = {
+                    id: compiledResource.id,
+                    json,
+                    conditions,
+                    isPartial: candidate.isPartial,
+                    mergeMethod: candidate.mergeMethod,
+                    resourceTypeName: resourceType.key
+                };
+                return builder.addLooseCandidate(candidateDecl).aggregateError(errors);
+            })
+                .aggregateError(errors);
+        }
+        return errors.returnOrReport((0, ts_utils_1.succeed)(true));
+    }
+}
+exports.ResourceManagerBuilder = ResourceManagerBuilder;
+//# sourceMappingURL=resourceManagerBuilder.js.map