@fgv/ts-res 5.0.0-22 → 5.0.0-24

package/lib/packlets/resources/candidateValueCollector.d.ts

@@ -0,0 +1,55 @@
+import { JsonValue } from '@fgv/ts-json-base';
+import { Hash, Result, ValidatingCollector } from '@fgv/ts-utils';
+import { CandidateValue } from './candidateValue';
+/**
+ * Parameters for creating a {@link Resources.CandidateValueCollector}.
+ * @public
+ */
+export interface ICandidateValueCollectorCreateParams {
+    /**
+     * Optional normalizer to use for normalizing JSON values.
+     * If not provided, a default Crc32Normalizer will be used.
+     */
+    normalizer?: Hash.HashingNormalizer;
+    /**
+     * Optional initial candidate values to add to the collection.
+     */
+    candidateValues?: (CandidateValue | JsonValue)[];
+}
+/**
+ * A `ValidatingCollector` for {@link Resources.CandidateValue | CandidateValues},
+ * which collects candidate values supplied as either {@link Resources.CandidateValue | CandidateValue} or
+ * `JsonValue`.
+ * @public
+ */
+export declare class CandidateValueCollector extends ValidatingCollector<CandidateValue> {
+    readonly normalizer: Hash.HashingNormalizer;
+    /**
+     * Constructor for a {@link Resources.CandidateValueCollector} object.
+     * @param params - Parameters to create the collector.
+     * @internal
+     */
+    protected constructor(params?: ICandidateValueCollectorCreateParams);
+    /**
+     * Creates a new {@link Resources.CandidateValueCollector} object.
+     * @param params - Parameters to create the collector.
+     * @returns `Success` with the new collector if successful,
+     * or `Failure` with an error message if not.
+     * @public
+     */
+    static create(params?: ICandidateValueCollectorCreateParams): Result<CandidateValueCollector>;
+    /**
+     * Returns an array of JSON values ordered by their indices.
+     * @returns Array of JsonValue objects in index order.
+     * @public
+     */
+    getValuesByIndex(): JsonValue[];
+    /**
+     * Converter method to handle CandidateValue | JsonValue.
+     * @param from - The value to convert.
+     * @returns `Success` with the CandidateValue if successful, or `Failure` with an error message if not.
+     * @internal
+     */
+    private _toCandidateValue;
+}
+//# sourceMappingURL=candidateValueCollector.d.ts.map

package/lib/packlets/resources/candidateValueCollector.js

@@ -0,0 +1,96 @@
+"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.CandidateValueCollector = void 0;
+const ts_json_base_1 = require("@fgv/ts-json-base");
+const ts_utils_1 = require("@fgv/ts-utils");
+const common_1 = require("../common");
+const candidateValue_1 = require("./candidateValue");
+/**
+ * A `ValidatingCollector` for {@link Resources.CandidateValue | CandidateValues},
+ * which collects candidate values supplied as either {@link Resources.CandidateValue | CandidateValue} or
+ * `JsonValue`.
+ * @public
+ */
+class CandidateValueCollector extends ts_utils_1.ValidatingCollector {
+    /**
+     * Constructor for a {@link Resources.CandidateValueCollector} object.
+     * @param params - Parameters to create the collector.
+     * @internal
+     */
+    constructor(params = {}) {
+        var _a, _b;
+        super({
+            converters: new ts_utils_1.Collections.KeyValueConverters({
+                key: common_1.Convert.candidateValueKey,
+                value: (from) => this._toCandidateValue(from)
+            })
+        });
+        this.normalizer = (_a = params === null || params === void 0 ? void 0 : params.normalizer) !== null && _a !== void 0 ? _a : new ts_utils_1.Hash.Crc32Normalizer();
+        (_b = params.candidateValues) === null || _b === void 0 ? void 0 : _b.forEach((candidateValue) => this.validating.add(candidateValue));
+    }
+    /**
+     * Creates a new {@link Resources.CandidateValueCollector} object.
+     * @param params - Parameters to create the collector.
+     * @returns `Success` with the new collector if successful,
+     * or `Failure` with an error message if not.
+     * @public
+     */
+    static create(params) {
+        return (0, ts_utils_1.captureResult)(() => new CandidateValueCollector(params));
+    }
+    /**
+     * Returns an array of JSON values ordered by their indices.
+     * @returns Array of JsonValue objects in index order.
+     * @public
+     */
+    getValuesByIndex() {
+        // Use the base class valuesByIndex() method to get CandidateValues in index order,
+        // then extract their JSON values
+        return this.valuesByIndex().map((candidateValue) => candidateValue.json);
+    }
+    /**
+     * Converter method to handle CandidateValue | JsonValue.
+     * @param from - The value to convert.
+     * @returns `Success` with the CandidateValue if successful, or `Failure` with an error message if not.
+     * @internal
+     */
+    _toCandidateValue(from) {
+        /* c8 ignore next 3 - functional code tested but coverage intermittently missed */
+        if (from instanceof candidateValue_1.CandidateValue) {
+            return (0, ts_utils_1.succeed)(from);
+        }
+        // Validate as JsonValue and create new CandidateValue
+        return ts_json_base_1.Validators.jsonValue
+            .validate(from)
+            .withErrorFormat((msg) => `Invalid JSON value: ${msg}`)
+            .onSuccess((jsonValue) => {
+            return candidateValue_1.CandidateValue.create({
+                json: jsonValue,
+                normalizer: this.normalizer
+            });
+        });
+    }
+}
+exports.CandidateValueCollector = CandidateValueCollector;
+//# sourceMappingURL=candidateValueCollector.js.map

package/lib/packlets/resources/index.d.ts

@@ -1,4 +1,6 @@
 export * from './candidateReducer';
+export * from './candidateValue';
+export * from './candidateValueCollector';
 export * from './resourceCandidate';
 export * from './resource';
 export * from './resourceBuilder';

package/lib/packlets/resources/index.js

@@ -36,6 +36,8 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./candidateReducer"), exports);
+__exportStar(require("./candidateValue"), exports);
+__exportStar(require("./candidateValueCollector"), exports);
 __exportStar(require("./resourceCandidate"), exports);
 __exportStar(require("./resource"), exports);
 __exportStar(require("./resourceBuilder"), exports);

package/lib/packlets/resources/resource.js

@@ -115,9 +115,9 @@ class Resource {
      */
     toCompiled(options) {
         const candidates = this._getMatchingCandidates(options).map((c) => ({
-            json: c.json,
             isPartial: c.isPartial,
-            mergeMethod: c.mergeMethod
+            mergeMethod: c.mergeMethod,
+            valueIndex: c.candidateValue.index
         }));
         return {
             id: this.id,

package/lib/packlets/resources/resourceBuilder.d.ts

@@ -5,6 +5,7 @@ import { ReadOnlyResourceTypeCollector, ResourceType } from '../resource-types';
 import { Resource } from './resource';
 import { ConditionSetCollector } from '../conditions';
 import { AbstractDecisionCollector } from '../decisions';
+import { CandidateValueCollector } from './candidateValueCollector';
 import * as ResourceJson from '../resource-json';
 import * as Context from '../context';
 /**
@@ -17,6 +18,7 @@ export interface IResourceBuilderCreateParams {
     conditionSets: ConditionSetCollector;
     resourceTypes: ReadOnlyResourceTypeCollector;
     decisions: AbstractDecisionCollector;
+    candidateValues: CandidateValueCollector;
 }
 /**
  * Possible result details returned by the resource builder
@@ -66,6 +68,10 @@ export declare class ResourceBuilder {
      * Collector for {@link Decisions.AbstractDecision | abstract decisions}.
      */
     protected _decisions: AbstractDecisionCollector;
+    /**
+     * Collector for candidate values.
+     */
+    protected _candidateValues: CandidateValueCollector;
     /**
      * Constructor for a {@link Resources.ResourceBuilder | ResourceBuilder} object.
      * @param params - Parameters to construct the new {@link Resources.ResourceBuilder | ResourceBuilder}.

package/lib/packlets/resources/resourceBuilder.js

@@ -56,6 +56,7 @@ class ResourceBuilder {
         this._resourceTypes = params.resourceTypes;
         this._conditionSets = params.conditionSets;
         this._decisions = params.decisions;
+        this._candidateValues = params.candidateValues;
         this._candidates = new ts_utils_1.ResultMap();
         if (params.typeName) {
             this._resourceType = this._resourceTypes.validating.get(params.typeName).orThrow();
@@ -93,7 +94,8 @@ class ResourceBuilder {
             id: this.id,
             resourceType: this._resourceType,
             decl: childDecl,
-            conditionSets: this._conditionSets
+            conditionSets: this._conditionSets,
+            candidateValues: this._candidateValues
         })
             .withDetail('failure', 'success')
             .onSuccess((candidate) => {

package/lib/packlets/resources/resourceCandidate.d.ts

@@ -3,6 +3,8 @@ import { CandidateCompleteness, QualifierName, ResourceId, ResourceValueMergeMet
 import { Condition, ConditionSet, ConditionSetCollector } from '../conditions';
 import * as ResourceJson from '../resource-json';
 import { ResourceType } from '../resource-types';
+import { CandidateValue } from './candidateValue';
+import { CandidateValueCollector } from './candidateValueCollector';
 import { Result } from '@fgv/ts-utils';
 import * as Context from '../context';
 import { IResourceCandidate } from '../runtime';
@@ -16,6 +18,7 @@ export interface IResourceCandidateCreateParams {
     resourceType?: ResourceType;
     parentConditions?: ReadonlyArray<Condition>;
     conditionSets: ConditionSetCollector;
+    candidateValues: CandidateValueCollector;
 }
 /**
  * Options for creating a {@link Resources.ResourceCandidate | ResourceCandidate} declaration.
@@ -43,10 +46,16 @@ export declare class ResourceCandidate implements IResourceCandidate {
      * is a possible instance.
      */
     readonly id: ResourceId;
+    /**
+     * The candidate value that contains the JSON representation of the instance data.
+     */
+    readonly candidateValue: CandidateValue;
     /**
      * The JSON representation of the instance data to be applied.
+     * @remarks
+     * This property provides access to the JSON data from the underlying candidate value.
      */
-    readonly json: JsonObject;
+    get json(): JsonObject;
     /**
      * The conditions under which this candidate applies.
      */

package/lib/packlets/resources/resourceCandidate.js

@@ -66,6 +66,14 @@ const ts_utils_1 = require("@fgv/ts-utils");
  * @public
  */
 class ResourceCandidate {
+    /**
+     * The JSON representation of the instance data to be applied.
+     * @remarks
+     * This property provides access to the JSON data from the underlying candidate value.
+     */
+    get json() {
+        return this.candidateValue.json;
+    }
     /**
      * The completeness of the candidate value.
      */
@@ -80,7 +88,7 @@ class ResourceCandidate {
     constructor(params) {
         var _a, _b;
         this.id = common_1.Validate.toResourceId(params.id).orThrow();
-        this.json = params.decl.json;
+        this.candidateValue = params.candidateValues.validating.getOrAdd(params.decl.json).orThrow();
         this.conditions = ResourceCandidate._mergeConditions(params.conditionSets, params.decl.conditions, params.parentConditions).orThrow();
         this.isPartial = (_a = params.decl.isPartial) !== null && _a !== void 0 ? _a : false;
         this.mergeMethod = (_b = params.decl.mergeMethod) !== null && _b !== void 0 ? _b : 'augment';
@@ -181,10 +189,8 @@ class ResourceCandidate {
             rc1.mergeMethod === rc2.mergeMethod &&
             conditions_1.ConditionSet.compare(rc1.conditions, rc2.conditions) === 0;
         if (equal) {
-            const normalizer = new ts_utils_1.Hash.Crc32Normalizer();
-            const n1 = normalizer.computeHash(rc1.json).orDefault('(n1 normalization failed)');
-            const n2 = normalizer.computeHash(rc2.json).orDefault('(n2 normalization failed)');
-            equal = n1 === n2;
+            // Compare candidate values by their keys for efficient JSON comparison
+            equal = rc1.candidateValue.key === rc2.candidateValue.key;
         }
         return equal;
     }

package/lib/packlets/resources/resourceManagerBuilder.d.ts

@@ -8,6 +8,7 @@ import { IResourceManager, ResourceTree } from '../runtime';
 import { ResourceBuilder, ResourceBuilderResultDetail } from './resourceBuilder';
 import { Resource } from './resource';
 import { ResourceCandidate } from './resourceCandidate';
+import { CandidateValueCollector } from './candidateValueCollector';
 import { IResourceDeclarationOptions, IResourceManagerCloneOptions } from './common';
 import * as ResourceJson from '../resource-json';
 import * as Context from '../context';
@@ -57,6 +58,11 @@ export declare class ResourceManagerBuilder implements IResourceManager<Resource
      * @internal
      */
     protected readonly _decisions: AbstractDecisionCollector;
+    /**
+     * The candidate value collector used by this resource manager.
+     * @internal
+     */
+    protected readonly _candidateValues: CandidateValueCollector;
     /**
      * The {@link Resources.ResourceBuilder | resource builders} used by this resource manager.
      * @internal
@@ -383,6 +389,7 @@ export declare class ResourceManagerBuilder implements IResourceManager<Resource
      * @param decision - The decision containing condition sets.
      * @param resourceType - The resource type for the candidates.
      * @param builder - The builder to add candidates to.
+     * @param candidateValues - Array of candidate values indexed by valueIndex.
      * @returns `Success` if all candidates were added successfully, `Failure` otherwise.
      * @internal
      */

package/lib/packlets/resources/resourceManagerBuilder.js

@@ -63,6 +63,7 @@ const common_1 = require("../common");
 const runtime_1 = require("../runtime");
 const resourceBuilder_1 = require("./resourceBuilder");
 const resource_1 = require("./resource");
+const candidateValueCollector_1 = require("./candidateValueCollector");
 const ResourceJson = __importStar(require("../resource-json"));
 const Context = __importStar(require("../context"));
 const Config = __importStar(require("../config"));
@@ -79,6 +80,7 @@ class ResourceManagerBuilder {
      * The {@link QualifierTypes.ReadOnlyQualifierTypeCollector | qualifier types} used by this resource manager.
      */
     get qualifierTypes() {
+        /* c8 ignore next 1 - functional code tested but coverage intermittently missed */
         return this.qualifiers.qualifierTypes;
     }
     /**
@@ -149,6 +151,7 @@ class ResourceManagerBuilder {
         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._candidateValues = candidateValueCollector_1.CandidateValueCollector.create().orThrow();
         this._resources = new ts_utils_1.ValidatingResultMap({
             converters: new ts_utils_1.Collections.KeyValueConverters({
                 key: common_1.Convert.resourceId,
@@ -234,7 +237,8 @@ class ResourceManagerBuilder {
             id,
             resourceTypes: this.resourceTypes,
             conditionSets: this._conditionSets,
-            decisions: this._decisions
+            decisions: this._decisions,
+            candidateValues: this._candidateValues
         }));
         /* c8 ignore next 6 - defense in depth against internal error */
         if (builderResult.isFailure()) {
@@ -259,7 +263,8 @@ class ResourceManagerBuilder {
             typeName: decl.resourceTypeName,
             resourceTypes: this.resourceTypes,
             conditionSets: this._conditionSets,
-            decisions: this._decisions
+            decisions: this._decisions,
+            candidateValues: this._candidateValues
         }));
         /* c8 ignore next 3 - defense in depth against internal error */
         if (getOrAddMessage !== undefined) {
@@ -494,6 +499,7 @@ class ResourceManagerBuilder {
             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)),
+            candidateValues: this._candidateValues.getValuesByIndex(),
             resources: Array.from(this._builtResources.values()).map((r) => r.toCompiled(options))
         };
         // Apply validation through the converter
@@ -848,7 +854,7 @@ class ResourceManagerBuilder {
             const decision = decisionResult.value;
             const resourceType = resourceTypeResult.value;
             // Create candidates from the decision's condition sets
-            ResourceManagerBuilder._createCandidatesFromDecision(compiledResource, decision, resourceType, builder).aggregateError(errors);
+            ResourceManagerBuilder._createCandidatesFromDecision(compiledResource, decision, resourceType, builder, compiledCollection.candidateValues).aggregateError(errors);
         }
         return errors.returnOrReport((0, ts_utils_1.succeed)(true));
     }
@@ -858,10 +864,11 @@ class ResourceManagerBuilder {
      * @param decision - The decision containing condition sets.
      * @param resourceType - The resource type for the candidates.
      * @param builder - The builder to add candidates to.
+     * @param candidateValues - Array of candidate values indexed by valueIndex.
      * @returns `Success` if all candidates were added successfully, `Failure` otherwise.
      * @internal
      */
-    static _createCandidatesFromDecision(compiledResource, decision, resourceType, builder) {
+    static _createCandidatesFromDecision(compiledResource, decision, resourceType, builder, candidateValues) {
         var _a;
         const errors = new ts_utils_1.MessageAggregator();
         // Match each candidate to its corresponding condition set
@@ -880,9 +887,9 @@ class ResourceManagerBuilder {
                     conditions = undefined;
                 }
             }
-            // Convert json value to JsonObject, handling undefined case
+            // Get json value from candidateValues array using valueIndex
             /* c8 ignore next 1 - defense in depth */
-            const rawJson = (_a = candidate.json) !== null && _a !== void 0 ? _a : {};
+            const rawJson = (_a = candidateValues[candidate.valueIndex]) !== null && _a !== void 0 ? _a : {};
             ts_json_base_1.Converters.jsonObject
                 .convert(rawJson)
                 .onSuccess((json) => {

package/lib/packlets/runtime/compiledResourceCollection.d.ts

@@ -1,10 +1,11 @@
 import { Collections, Result } from '@fgv/ts-utils';
 import { ReadOnlyConditionCollector, ReadOnlyConditionSetCollector } from '../conditions';
 import { ReadOnlyAbstractDecisionCollector } from '../decisions';
-import { QualifierCollector } from '../qualifiers';
-import { ResourceType, ResourceTypeCollector } from '../resource-types';
-import { QualifierType, QualifierTypeCollector } from '../qualifier-types';
+import { IReadOnlyQualifierCollector } from '../qualifiers';
+import { ResourceType, ReadOnlyResourceTypeCollector } from '../resource-types';
+import { QualifierType, ReadOnlyQualifierTypeCollector } from '../qualifier-types';
 import { ResourceId } from '../common';
+import { JsonValue } from '@fgv/ts-json-base';
 import { IResourceManager, IResource } from './iResourceManager';
 import * as ResourceJson from '../resource-json';
 import { ReadOnlyResourceTreeRoot } from './resource-tree';
@@ -40,23 +41,28 @@ export declare class CompiledResourceCollection implements IResourceManager<IRes
     private readonly _qualifierTypes;
     private readonly _qualifiers;
     private readonly _resourceTypes;
+    private readonly _candidateValues;
     private readonly _builtResources;
     private _cachedResourceTree?;
     /**
-     * A {@link QualifierTypes.QualifierTypeCollector | QualifierTypeCollector} which
+     * A {@link QualifierTypes.ReadOnlyQualifierTypeCollector | ReadOnlyQualifierTypeCollector} which
      * contains the {@link QualifierTypes.QualifierType | qualifier types} used in this collection.
      */
-    get qualifierTypes(): QualifierTypeCollector;
+    get qualifierTypes(): ReadOnlyQualifierTypeCollector;
     /**
-     * A {@link Qualifiers.QualifierCollector | QualifierCollector} which
+     * A {@link Qualifiers.IReadOnlyQualifierCollector | ReadOnlyQualifierCollector} which
      * contains the {@link Qualifiers.Qualifier | qualifiers} used in this collection.
      */
-    get qualifiers(): QualifierCollector;
+    get qualifiers(): IReadOnlyQualifierCollector;
     /**
      * A {@link ResourceTypes.ResourceTypeCollector | ResourceTypeCollector} which
      * contains the {@link ResourceTypes.ResourceType | resource types} used in this collection.
      */
-    get resourceTypes(): ResourceTypeCollector;
+    get resourceTypes(): ReadOnlyResourceTypeCollector;
+    /**
+     * The candidate values in the collection.
+     */
+    get candidateValues(): ReadonlyArray<JsonValue>;
     /**
      * {@inheritdoc Runtime.IResourceManager.builtResources}
      */
@@ -154,6 +160,12 @@ export declare class CompiledResourceCollection implements IResourceManager<IRes
      * @internal
      */
     private _buildDecisions;
+    /**
+     * Gets a candidate value from the collection.
+     * @param valueIndex - The index of the candidate value to get.
+     * @returns
+     */
+    private _getCandidateValue;
     /**
      * Reconstructs a ValidatingResultMap of resources from compiled data.
      * @param compiled - The compiled resource collection

package/lib/packlets/runtime/compiledResourceCollection.js

@@ -75,14 +75,14 @@ const Context = __importStar(require("../context"));
  */
 class CompiledResourceCollection {
     /**
-     * A {@link QualifierTypes.QualifierTypeCollector | QualifierTypeCollector} which
+     * A {@link QualifierTypes.ReadOnlyQualifierTypeCollector | ReadOnlyQualifierTypeCollector} which
      * contains the {@link QualifierTypes.QualifierType | qualifier types} used in this collection.
      */
     get qualifierTypes() {
         return this._qualifierTypes;
     }
     /**
-     * A {@link Qualifiers.QualifierCollector | QualifierCollector} which
+     * A {@link Qualifiers.IReadOnlyQualifierCollector | ReadOnlyQualifierCollector} which
      * contains the {@link Qualifiers.Qualifier | qualifiers} used in this collection.
      */
     get qualifiers() {
@@ -95,6 +95,12 @@ class CompiledResourceCollection {
     get resourceTypes() {
         return this._resourceTypes;
     }
+    /**
+     * The candidate values in the collection.
+     */
+    get candidateValues() {
+        return this._candidateValues;
+    }
     /**
      * {@inheritdoc Runtime.IResourceManager.builtResources}
      */
@@ -133,6 +139,7 @@ class CompiledResourceCollection {
         this.conditions = conditionCollector;
         this.conditionSets = conditionSetCollector;
         this.decisions = decisionCollector;
+        this._candidateValues = [...params.compiledCollection.candidateValues];
         // Build resources from compiled data
         this._builtResources = this._buildResources(params.compiledCollection, this._resourceTypes, decisionCollector).orThrow();
     }
@@ -381,6 +388,21 @@ class CompiledResourceCollection {
         }
         return errors.hasMessages ? (0, ts_utils_1.fail)(errors.toString()) : (0, ts_utils_1.succeed)(decisionCollector);
     }
+    /**
+     * Gets a candidate value from the collection.
+     * @param valueIndex - The index of the candidate value to get.
+     * @returns
+     */
+    _getCandidateValue(valueIndex) {
+        if (valueIndex < 0 || valueIndex >= this._candidateValues.length) {
+            return (0, ts_utils_1.fail)(`Invalid candidate value index ${valueIndex}`);
+        }
+        /* c8 ignore next 3 - defensive coding for invalid candidate value conversion */
+        if (!(0, ts_json_base_1.isJsonObject)(this._candidateValues[valueIndex])) {
+            return (0, ts_utils_1.fail)(`${valueIndex}: candidate value not a JSON object.`);
+        }
+        return (0, ts_utils_1.succeed)(this._candidateValues[valueIndex]);
+    }
     /**
      * Reconstructs a ValidatingResultMap of resources from compiled data.
      * @param compiled - The compiled resource collection
@@ -413,7 +435,7 @@ class CompiledResourceCollection {
             }
             const decision = decisionResult.value;
             // Build candidates from compiled data
-            const candidateDeclsResult = (0, ts_utils_1.mapResults)(compiledResource.candidates.map((compiledCandidate) => ts_json_base_1.Converters.jsonObject.convert(compiledCandidate.json).onSuccess((json) => {
+            const candidateDeclsResult = (0, ts_utils_1.mapResults)(compiledResource.candidates.map((compiledCandidate) => this._getCandidateValue(compiledCandidate.valueIndex).onSuccess((json) => {
                 return (0, ts_utils_1.succeed)({
                     json,
                     isPartial: compiledCandidate.isPartial,
@@ -431,7 +453,6 @@ class CompiledResourceCollection {
                 isPartial: candidateDecl.isPartial,
                 mergeMethod: candidateDecl.mergeMethod
             }));
-            // Create a ConcreteDecision from the abstract decision and candidate values
             const candidatesWithConditionSets = decision.candidates.map((baseCandidate, idx) => ({
                 conditionSet: baseCandidate.conditionSet,
                 value: candidates[idx].json

package/lib/packlets/runtime/index.d.ts

@@ -3,6 +3,7 @@ export * from './iResourceManager';
 export * from './context/simpleContextQualifierProvider';
 export * from './context/validatingSimpleContextQualifierProvider';
 export * from './resourceResolver';
+export * from './resourceTreeResolver';
 export * from './conditionSetResolutionResult';
 export * from './cacheListener';
 export * from './cacheMetrics';

package/lib/packlets/runtime/index.js

@@ -63,6 +63,7 @@ __exportStar(require("./iResourceManager"), exports);
 __exportStar(require("./context/simpleContextQualifierProvider"), exports);
 __exportStar(require("./context/validatingSimpleContextQualifierProvider"), exports);
 __exportStar(require("./resourceResolver"), exports);
+__exportStar(require("./resourceTreeResolver"), exports);
 __exportStar(require("./conditionSetResolutionResult"), exports);
 __exportStar(require("./cacheListener"), exports);
 __exportStar(require("./cacheMetrics"), exports);

package/lib/packlets/runtime/resource-tree/common.d.ts

@@ -49,7 +49,7 @@ export type IReadOnlyResourceTreeNode<T> = IReadOnlyResourceTreeLeaf<T> | IReadO
  * Interface for a read-only result-based resource tree with navigation methods.
  * @public
  */
-export interface IReadOnlyResourceTreeChildren<T, TID extends string = ResourceId, TNAME extends string = ResourceName> extends IReadOnlyResultMap<ResourceName, IReadOnlyResourceTreeNode<T>> {
+export interface IReadOnlyResourceTreeChildren<T, TID extends string = ResourceId, TNAME extends string = ResourceName> extends IReadOnlyResultMap<TNAME, IReadOnlyResourceTreeNode<T>> {
     /**
      * Gets a tree node by its full ResourceId path.
      * @param id - The ResourceId path to look up