@fgv/ts-res 5.0.0-3 → 5.0.0-30

package/lib/packlets/runtime/cacheMetrics.js

@@ -87,6 +87,9 @@ exports.AggregateCacheMetrics = AggregateCacheMetrics;
  * @public
  */
 class ResourceResolverCacheMetricsListener {
+    get numContextErrors() {
+        return this._contextErrors;
+    }
     constructor(factoryOrMetrics) {
         if (typeof factoryOrMetrics === 'function') {
             this._metrics = {
@@ -98,6 +101,7 @@ class ResourceResolverCacheMetricsListener {
         else {
             this._metrics = factoryOrMetrics;
         }
+        this._contextErrors = 0;
     }
     /**
      * Get the metrics for all cache types.
@@ -124,6 +128,12 @@ class ResourceResolverCacheMetricsListener {
     onCacheError(cache, index) {
         this._metrics[cache].onError(index);
     }
+    /**
+     * {@inheritDoc Runtime.IResourceResolverCacheListener.onContextError}
+     */
+    onContextError(qualifier, error) {
+        this._contextErrors++;
+    }
     /**
      * {@inheritDoc Runtime.IResourceResolverCacheListener.onCacheClear}
      */
@@ -137,6 +147,7 @@ class ResourceResolverCacheMetricsListener {
         this._metrics.condition.reset();
         this._metrics.conditionSet.reset();
         this._metrics.decision.reset();
+        this._contextErrors = 0;
     }
 }
 exports.ResourceResolverCacheMetricsListener = ResourceResolverCacheMetricsListener;

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

@@ -1,13 +1,14 @@
 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 { IReadOnlyResourceTreeRoot } from './resource-tree';
+import { ReadOnlyResourceTreeRoot } from './resource-tree';
 import * as Context from '../context';
 /**
  * Interface for parameters to create a {@link Runtime.CompiledResourceCollection | CompiledResourceCollection}.
@@ -33,30 +34,35 @@ export interface ICompiledResourceCollectionCreateParams {
  * and use pre-compiled resource collections without rebuilding them from scratch.
  * @public
  */
-export declare class CompiledResourceCollection implements IResourceManager {
+export declare class CompiledResourceCollection implements IResourceManager<IResource> {
     readonly conditions: ReadOnlyConditionCollector;
     readonly conditionSets: ReadOnlyConditionSetCollector;
     readonly decisions: ReadOnlyAbstractDecisionCollector;
     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}
      */
@@ -105,7 +111,7 @@ export declare class CompiledResourceCollection implements IResourceManager {
      * @returns Result containing the resource tree root, or failure if tree construction fails
      * @public
      */
-    getBuiltResourceTree(): Result<IReadOnlyResourceTreeRoot<IResource>>;
+    getBuiltResourceTree(): Result<ReadOnlyResourceTreeRoot<IResource>>;
     /**
      * Reconstructs a QualifierTypeCollector from compiled data.
      * @param compiled - The compiled resource collection
@@ -154,6 +160,12 @@ export declare class CompiledResourceCollection implements IResourceManager {
      * @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
@@ -446,9 +467,16 @@ class CompiledResourceCollection {
                 continue;
             }
             const concreteDecision = concreteDecisionResult.value;
+            const { value: name, message: nameError } = common_1.Helpers.getNameForResourceId(compiledResource.id);
+            /* c8 ignore next 4 - defense in depth nearly impossible to reproduce */
+            if (nameError !== undefined) {
+                errors.addMessage(`Failed to get name for resource ${compiledResource.id}: ${nameError}`);
+                continue;
+            }
             // Create minimal resource that implements IResource
             const resource = {
                 id: compiledResource.id,
+                name,
                 resourceType,
                 decision: concreteDecision,
                 candidates

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

@@ -3,8 +3,9 @@ import { JsonObject } from '@fgv/ts-json-base';
 import { ReadOnlyConditionCollector, ReadOnlyConditionSetCollector } from '../conditions';
 import { ReadOnlyAbstractDecisionCollector, ConcreteDecision } from '../decisions';
 import { ResourceId, ResourceValueMergeMethod } from '../common';
-import { ResourceType } from '../resource-types';
+import { IResourceType } from '../resource-types';
 import { IContextDecl, IValidatedContextDecl } from '../context';
+import { IReadOnlyResourceTreeRoot } from './resource-tree';
 /**
  * Runtime representation of a resource candidate with the minimal data needed for resolution.
  * @public
@@ -30,8 +31,10 @@ export interface IResourceCandidate {
 export interface IResource {
     /** The resource identifier */
     readonly id: string;
+    /** The resource name */
+    readonly name: string;
     /** The resource type */
-    readonly resourceType: ResourceType;
+    readonly resourceType: IResourceType;
     /** The decision used to select candidates */
     readonly decision: ConcreteDecision;
     /** The available candidates for this resource */
@@ -43,7 +46,7 @@ export interface IResource {
  * implementations without requiring the full ResourceManagerBuilder build mechanics.
  * @public
  */
-export interface IResourceManager {
+export interface IResourceManager<TR extends IResource = IResource> {
     /**
      * A {@link Conditions.ReadOnlyConditionCollector | ReadOnlyConditionCollector} which
      * contains the {@link Conditions.Condition | conditions} used by resource candidates.
@@ -64,12 +67,17 @@ export interface IResourceManager {
      * @param id - The resource identifier
      * @returns Success with the runtime resource if found, Failure otherwise
      */
-    getBuiltResource(id: string): Result<IResource>;
+    getBuiltResource(id: string): Result<TR>;
+    /**
+     * Gets a resource tree built from the resources in this resource manager.
+     * @returns Result containing the resource tree root, or failure if tree construction fails
+     */
+    getBuiltResourceTree(): Result<IReadOnlyResourceTreeRoot<TR>>;
     /**
      * A read-only result map of all built resources, keyed by resource ID.
      * Resources are built on-demand when accessed and returns Results for error handling.
      */
-    readonly builtResources: Collections.IReadOnlyValidatingResultMap<ResourceId, IResource>;
+    readonly builtResources: Collections.IReadOnlyValidatingResultMap<ResourceId, TR>;
     /**
      * The number of resources in this resource manager.
      */

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

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

@@ -14,7 +14,7 @@ import { IReadOnlyResourceTreeBranch, IReadOnlyResourceTreeChildren, IReadOnlyRe
  * strongly-typed internal tree operations, ensuring type safety and consistent
  * error handling throughout the resource tree navigation.
  *
- * @internal
+ * @public
  */
 export declare class ResourceTreeChildrenValidator<T> implements IReadOnlyResourceTreeChildren<T, string, string> {
     private readonly _inner;
@@ -69,17 +69,17 @@ export declare class ResourceTreeChildrenValidator<T> implements IReadOnlyResour
      */
     forEach(cb: (value: unknown, key: string, map: IReadOnlyResultMap<string, unknown>, thisArg?: unknown) => void, arg?: unknown): void;
     /**
-     * Gets a child node by its ResourceName key with detailed error information.
-     * @param key - The ResourceName key to look up
+     * Gets a child node by its string key with detailed error information.
+     * @param key - The string key to look up
      * @returns DetailedResult containing the node if found, or failure with details
      */
-    get(key: ResourceName): DetailedResult<IReadOnlyResourceTreeNode<T>, Collections.ResultMapResultDetail>;
+    get(key: string): DetailedResult<IReadOnlyResourceTreeNode<T>, Collections.ResultMapResultDetail>;
     /**
-     * Checks if a child node exists at the given ResourceName key.
-     * @param key - The ResourceName key to check
+     * Checks if a child node exists at the given string key.
+     * @param key - The string key to check
      * @returns True if a child node exists at the key, false otherwise
      */
-    has(key: ResourceName): boolean;
+    has(key: string): boolean;
     /**
      * Returns an iterator of ResourceName keys for all child nodes.
      * @returns Map iterator for all child node keys

package/lib/packlets/runtime/resource-tree/resourceTreeChildrenValidator.js

@@ -37,7 +37,7 @@ const ts_utils_1 = require("@fgv/ts-utils");
  * strongly-typed internal tree operations, ensuring type safety and consistent
  * error handling throughout the resource tree navigation.
  *
- * @internal
+ * @public
  */
 class ResourceTreeChildrenValidator {
     /**
@@ -121,8 +121,8 @@ class ResourceTreeChildrenValidator {
         }
     }
     /**
-     * Gets a child node by its ResourceName key with detailed error information.
-     * @param key - The ResourceName key to look up
+     * Gets a child node by its string key with detailed error information.
+     * @param key - The string key to look up
      * @returns DetailedResult containing the node if found, or failure with details
      */
     get(key) {
@@ -132,8 +132,8 @@ class ResourceTreeChildrenValidator {
         return (0, ts_utils_1.failWithDetail)(`${key}: invalid resource name.`, 'invalid-key');
     }
     /**
-     * Checks if a child node exists at the given ResourceName key.
-     * @param key - The ResourceName key to check
+     * Checks if a child node exists at the given string key.
+     * @param key - The string key to check
      * @returns True if a child node exists at the key, false otherwise
      */
     has(key) {

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

@@ -1,5 +1,6 @@
 import { Result } from '@fgv/ts-utils';
 import { JsonValue } from '@fgv/ts-json-base';
+import { IResourceResolver } from '../common';
 import { Condition, ConditionSet } from '../conditions';
 import { AbstractDecision } from '../decisions';
 import { ReadOnlyQualifierTypeCollector } from '../qualifier-types';
@@ -7,6 +8,7 @@ import { IContextQualifierProvider } from './context';
 import { IResourceManager, IResource, IResourceCandidate } from './iResourceManager';
 import { ConditionSetResolutionResult, IConditionMatchResult } from './conditionSetResolutionResult';
 import { IResourceResolverCacheListener } from './cacheListener';
+import { IReadOnlyQualifierCollector } from '../qualifiers';
 /**
  * Represents the cached result of resolving a decision.
  * Contains either a failure indicator or a list of instance indices for matching condition sets,
@@ -20,6 +22,19 @@ export type DecisionResolutionResult = {
     instanceIndices: ReadonlyArray<number>;
     defaultInstanceIndices: ReadonlyArray<number>;
 };
+/**
+ * Options for configuring a {@link Runtime.ResourceResolver | ResourceResolver}.
+ * @public
+ */
+export interface IResourceResolverOptions {
+    /**
+     * Controls whether null values in resource composition should suppress properties
+     * instead of setting them to null. When true, properties with null values from
+     * higher-priority partial candidates will be omitted from the final composed resource.
+     * @defaultValue false
+     */
+    suppressNullAsDelete?: boolean;
+}
 /**
  * Parameters for creating a {@link Runtime.ResourceResolver | ResourceResolver}.
  * @public
@@ -44,6 +59,10 @@ export interface IResourceResolverCreateParams {
      * An optional listener for {@link Runtime.ResourceResolver | ResourceResolver} cache activity.
      */
     listener?: IResourceResolverCacheListener;
+    /**
+     * Optional configuration options for the {@link Runtime.ResourceResolver | ResourceResolver}.
+     */
+    options?: IResourceResolverOptions;
 }
 /**
  * High-performance runtime resource resolver with O(1) condition caching.
@@ -51,7 +70,7 @@ export interface IResourceResolverCreateParams {
  * and caching results for optimal performance.
  * @public
  */
-export declare class ResourceResolver {
+export declare class ResourceResolver implements IResourceResolver {
     /**
      * The resource manager that defines available resources and provides condition access.
      */
@@ -64,6 +83,14 @@ export declare class ResourceResolver {
      * The context qualifier provider that resolves qualifier values.
      */
     readonly contextQualifierProvider: IContextQualifierProvider;
+    /**
+     * The configuration options for this resource resolver.
+     */
+    readonly options: IResourceResolverOptions;
+    /**
+     * The readonly qualifier collector that provides qualifier implementations.
+     */
+    get qualifiers(): IReadOnlyQualifierCollector;
     /**
      * The cache array for resolved conditions, indexed by condition index for O(1) lookup.
      * Each entry stores the resolved {@link Runtime.IConditionMatchResult | condition match result} for
@@ -148,6 +175,15 @@ export declare class ResourceResolver {
      * @public
      */
     resolveResource(resource: IResource): Result<IResourceCandidate>;
+    /**
+     * Resolves a resource by finding the best matching candidate.
+     * Uses the resource's associated decision to determine the best match based on the current context.
+     * @param resource - The string id of the resource to resolve.
+     * @returns `Success` with the best matching candidate if successful,
+     * or `Failure` with an error message if no candidates match or resolution fails.
+     * @public
+     */
+    resolveResource(resource: string): Result<IResourceCandidate>;
     /**
      * Resolves all matching resource candidates in priority order.
      * Uses the resource's associated decision to determine all matching candidates based on the current context.
@@ -157,6 +193,15 @@ export declare class ResourceResolver {
      * @public
      */
     resolveAllResourceCandidates(resource: IResource): Result<ReadonlyArray<IResourceCandidate>>;
+    /**
+     * Resolves all matching resource candidates in priority order.
+     * Uses the resource's associated decision to determine all matching candidates based on the current context.
+     * @param resource - The string id of the resource to resolve.
+     * @returns `Success` with an array of all matching candidates in priority order if successful,
+     * or `Failure` with an error message if no candidates match or resolution fails.
+     * @public
+     */
+    resolveAllResourceCandidates(resource: string): Result<ReadonlyArray<IResourceCandidate>>;
     /**
      * Resolves a resource to a composed value by merging matching candidates according to their merge methods.
      * Starting from the highest priority candidates, finds the first "full" candidate and merges all higher
@@ -167,6 +212,20 @@ export declare class ResourceResolver {
      * @public
      */
     resolveComposedResourceValue(resource: IResource): Result<JsonValue>;
+    /**
+     * Resolves a resource to a composed value by merging matching candidates according to their merge methods.
+     * Starting from the highest priority candidates, finds the first "full" candidate and merges all higher
+     * priority "partial" candidates into it in ascending order of priority.
+     * @param resource - The string id of the resource to resolve.
+     * @returns `Success` with the composed JsonValue if successful,
+     * or `Failure` with an error message if no candidates match or resolution fails.
+     * @public
+     */
+    resolveComposedResourceValue(resource: string): Result<JsonValue>;
+    /**
+     * {@inheritDoc IResourceResolver.withContext}
+     */
+    withContext(context: Record<string, string>): Result<ResourceResolver>;
     /**
      * Clears all caches (condition, condition set, and decision), forcing all cached items
      * to be re-evaluated on next access. This should be called when the context changes and cached