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

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

package/lib/packlets/runtime/resourceResolver.js

@@ -26,6 +26,7 @@ const ts_utils_1 = require("@fgv/ts-utils");
 const ts_json_base_1 = require("@fgv/ts-json-base");
 const ts_json_1 = require("@fgv/ts-json");
 const common_1 = require("../common");
+const context_1 = require("./context");
 const conditionSetResolutionResult_1 = require("./conditionSetResolutionResult");
 /**
  * High-performance runtime resource resolver with O(1) condition caching.
@@ -34,6 +35,12 @@ const conditionSetResolutionResult_1 = require("./conditionSetResolutionResult")
  * @public
  */
 class ResourceResolver {
+    /**
+     * The readonly qualifier collector that provides qualifier implementations.
+     */
+    get qualifiers() {
+        return this.contextQualifierProvider.qualifiers;
+    }
     /**
      * 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
@@ -61,9 +68,13 @@ class ResourceResolver {
      * @param params - {@link Runtime.IResourceResolverCreateParams | Parameters} used to create the resolver.
      */
     constructor(params) {
+        var _a, _b;
         this.resourceManager = params.resourceManager;
         this.qualifierTypes = params.qualifierTypes;
         this.contextQualifierProvider = params.contextQualifierProvider;
+        this.options = {
+            suppressNullAsDelete: (_b = (_a = params.options) === null || _a === void 0 ? void 0 : _a.suppressNullAsDelete) !== null && _b !== void 0 ? _b : false
+        };
         // Initialize condition cache array with size matching the condition collector
         const conditionCollectorSize = this.resourceManager.conditions.size;
         this._conditionCache = new Array(conditionCollectorSize);
@@ -94,7 +105,7 @@ class ResourceResolver {
      * @public
      */
     resolveCondition(condition) {
-        var _a, _b, _c, _d;
+        var _a, _b, _c;
         // Get the condition's index for cache lookup
         const conditionIndex = condition.index;
         if (conditionIndex === undefined) {
@@ -107,16 +118,20 @@ class ResourceResolver {
             return (0, ts_utils_1.succeed)(cachedResult);
         }
         // Resolve the condition by getting qualifier value and evaluating with qualifier type
-        const qualifierValueResult = this.contextQualifierProvider.get(condition.qualifier);
-        if (qualifierValueResult.isFailure()) {
-            (_b = this._listener) === null || _b === void 0 ? void 0 : _b.onCacheError('condition', conditionIndex);
-            return (0, ts_utils_1.fail)(`Failed to get qualifier value for "${condition.qualifier.name}": ${qualifierValueResult.message}`);
-        }
-        const qualifierValue = qualifierValueResult.value;
-        // Evaluate the condition using the qualifier type's matching logic
-        const score = condition.qualifier.type.matches(condition.value, qualifierValue, condition.operator);
+        const score = this.contextQualifierProvider
+            .get(condition.qualifier)
+            .onSuccess((qualifierValue) => {
+            // Evaluate the condition using the qualifier type's matching logic
+            return (0, ts_utils_1.succeed)(condition.qualifier.type.matches(condition.value, qualifierValue, condition.operator));
+        })
+            .onFailure((err) => {
+            var _a;
+            (_a = this._listener) === null || _a === void 0 ? void 0 : _a.onContextError(condition.qualifier.name, err);
+            return (0, ts_utils_1.fail)(err);
+        })
+            .orDefault(common_1.NoMatch);
         const priority = condition.priority;
-        const scoreAsDefault = (_c = condition.scoreAsDefault) !== null && _c !== void 0 ? _c : common_1.NoMatch;
+        const scoreAsDefault = (_b = condition.scoreAsDefault) !== null && _b !== void 0 ? _b : common_1.NoMatch;
         const matchResult = score > common_1.NoMatch
             ? { score, priority, matchType: 'match' }
             : scoreAsDefault > common_1.NoMatch
@@ -124,7 +139,7 @@ class ResourceResolver {
                 : { score: common_1.NoMatch, priority, matchType: 'noMatch' };
         // Cache the resolved value for future O(1) lookup
         this._conditionCache[conditionIndex] = matchResult;
-        (_d = this._listener) === null || _d === void 0 ? void 0 : _d.onCacheMiss('condition', conditionIndex);
+        (_c = this._listener) === null || _c === void 0 ? void 0 : _c.onCacheMiss('condition', conditionIndex);
         return (0, ts_utils_1.succeed)(matchResult);
     }
     /**
@@ -153,8 +168,8 @@ class ResourceResolver {
         let matchType = 'match';
         for (const condition of conditionSet.conditions) {
             const { value: conditionResult, message: conditionMessage } = this.resolveCondition(condition);
+            /* c8 ignore next 4 - defensive coding: extreme internal error scenario not reachable in normal operation */
             if (conditionMessage !== undefined) {
-                /* c8 ignore next 2 - defensive coding: extreme internal error scenario not reachable in normal operation */
                 (_b = this._listener) === null || _b === void 0 ? void 0 : _b.onCacheError('conditionSet', conditionSetIndex);
                 return (0, ts_utils_1.fail)(`Failed to resolve condition "${condition.key}": ${conditionMessage}`);
             }
@@ -176,6 +191,7 @@ class ResourceResolver {
                     return (0, ts_utils_1.fail)(`${conditionSetIndex}: error creating condition set resolution result: ${err}`);
                 });
             }
+            /* c8 ignore next 3 - edge case: matchAsDefault fallback logic rarely triggered */
             if (conditionResult.matchType === 'matchAsDefault') {
                 matchType = 'matchAsDefault';
             }
@@ -223,8 +239,8 @@ class ResourceResolver {
         for (let instanceIndex = 0; instanceIndex < decision.candidates.length; instanceIndex++) {
             const candidate = decision.candidates[instanceIndex];
             const conditionSetResult = this.resolveConditionSet(candidate.conditionSet);
+            /* c8 ignore next 4 - defensive coding: extreme internal error scenario not reachable in normal operation */
             if (conditionSetResult.isFailure()) {
-                /* c8 ignore next 2 - defensive coding: extreme internal error scenario not reachable in normal operation */
                 (_b = this._listener) === null || _b === void 0 ? void 0 : _b.onCacheError('decision', decisionIndex);
                 return (0, ts_utils_1.fail)(`${decision.key}: Failed to resolve condition set": ${conditionSetResult.message}`);
             }
@@ -237,6 +253,7 @@ class ResourceResolver {
                 });
             }
             else if (resolution.matchType === 'matchAsDefault') {
+                /* c8 ignore next 4 - edge case: default matching instances rarely used in practice */
                 matchingDefaultInstanceResults.push({
                     index: instanceIndex,
                     result: resolution
@@ -260,15 +277,14 @@ class ResourceResolver {
         (_c = this._listener) === null || _c === void 0 ? void 0 : _c.onCacheMiss('decision', decisionIndex);
         return (0, ts_utils_1.succeed)(successResult);
     }
-    /**
-     * 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 {@link Resources.Resource | 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) {
+    resolveResource(idOrResource) {
+        /* c8 ignore next 4 - defensive coding: string resource resolution should use direct resource calls */
+        if (typeof idOrResource === 'string') {
+            return this.resourceManager
+                .getBuiltResource(idOrResource)
+                .onSuccess((resource) => this.resolveResource(resource));
+        }
+        const resource = idOrResource;
         // Get the abstract decision from the resource's concrete decision
         const abstractDecision = resource.decision.baseDecision;
         // Resolve the decision to get candidate indices in priority order
@@ -293,15 +309,14 @@ class ResourceResolver {
         const bestCandidate = resource.candidates[candidateIndex];
         return (0, ts_utils_1.succeed)(bestCandidate);
     }
-    /**
-     * 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 {@link Resources.Resource | 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) {
+    resolveAllResourceCandidates(idOrResource) {
+        /* c8 ignore next 4 - defensive coding: string resource resolution should use direct resource calls */
+        if (typeof idOrResource === 'string') {
+            return this.resourceManager
+                .getBuiltResource(idOrResource)
+                .onSuccess((resource) => this.resolveAllResourceCandidates(resource));
+        }
+        const resource = idOrResource;
         // Get the abstract decision from the resource's concrete decision
         const abstractDecision = resource.decision.baseDecision;
         // Resolve the decision to get candidate indices in priority order
@@ -337,16 +352,14 @@ class ResourceResolver {
         }
         return (0, ts_utils_1.succeed)(candidates);
     }
-    /**
-     * 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 {@link Resources.Resource | 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) {
+    resolveComposedResourceValue(idOrResource) {
+        /* c8 ignore next 4 - defensive coding: string resource resolution should use direct resource calls */
+        if (typeof idOrResource === 'string') {
+            return this.resourceManager
+                .getBuiltResource(idOrResource)
+                .onSuccess((resource) => this.resolveComposedResourceValue(resource));
+        }
+        const resource = idOrResource;
         return this.resolveAllResourceCandidates(resource).onSuccess((candidates) => {
             /* c8 ignore next 3 - defense in depth should never occur */
             if (candidates.length === 0) {
@@ -370,9 +383,22 @@ class ResourceResolver {
             // If no full candidate found, use the last candidate as the base
             const baseCandidateIndex = fullCandidateIndex >= 0 ? fullCandidateIndex : candidates.length - 1;
             const baseCandidate = candidates[baseCandidateIndex];
-            // If there are no partial candidates to merge, return the base candidate's value
+            // If there are no partial candidates to merge, but null-as-delete is enabled,
+            // still process through JsonEditor to handle null properties in the base candidate
             if (partialCandidates.length === 0) {
-                return (0, ts_utils_1.succeed)(baseCandidate.json);
+                if (this.options.suppressNullAsDelete || !(0, ts_json_base_1.isJsonObject)(baseCandidate.json)) {
+                    return (0, ts_utils_1.succeed)(baseCandidate.json);
+                }
+                // Process single candidate through JsonEditor to apply null-as-delete
+                const editor = ts_json_1.JsonEditor.create({
+                    merge: {
+                        arrayMergeBehavior: 'replace',
+                        nullAsDelete: true
+                    }
+                }).orThrow(); // Should never fail with valid options
+                return editor
+                    .mergeObjectsInPlace({}, [baseCandidate.json])
+                    .withErrorFormat((err) => `${resource.id}: Composition failed: ${err}`);
             }
             const allCandidates = [
                 baseCandidate.json,
@@ -382,10 +408,11 @@ class ResourceResolver {
             if (allCandidates.length !== partialCandidates.length + 1) {
                 return (0, ts_utils_1.fail)(`${resource.id}: Unable to compose non-object candidate values.`);
             }
-            // Create JsonEditor with array replacement behavior for resource composition
+            // Create JsonEditor with array replacement behavior and null-as-delete for resource composition
             const editor = ts_json_1.JsonEditor.create({
                 merge: {
-                    arrayMergeBehavior: 'replace'
+                    arrayMergeBehavior: 'replace',
+                    nullAsDelete: !this.options.suppressNullAsDelete
                 }
             }).orThrow(); // Should never fail with valid options
             return editor
@@ -393,6 +420,23 @@ class ResourceResolver {
                 .withErrorFormat((err) => `${resource.id}: Composition failed: ${err}`);
         });
     }
+    /**
+     * {@inheritDoc IResourceResolver.withContext}
+     */
+    withContext(context) {
+        const { resourceManager, qualifierTypes, options } = this;
+        return context_1.ValidatingSimpleContextQualifierProvider.create({
+            qualifiers: this.qualifiers,
+            qualifierValues: context
+        }).onSuccess((contextQualifierProvider) => {
+            return ResourceResolver.create({
+                resourceManager,
+                qualifierTypes,
+                options,
+                contextQualifierProvider
+            });
+        });
+    }
     /**
      * 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

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

@@ -0,0 +1,152 @@
+import { Result } from '@fgv/ts-utils';
+import { JsonValue, JsonObject } from '@fgv/ts-json-base';
+import { IResource } from './iResourceManager';
+import { IReadOnlyResourceTreeNode, IReadOnlyResourceTreeRoot } from './resource-tree/common';
+import { ResourceResolver } from './resourceResolver';
+/**
+ * Type for handling resource resolution errors during tree traversal.
+ * The handler receives the resource that failed to resolve, the error message, and the resolver for recovery attempts.
+ * It can return:
+ * - Success(undefined) to omit the property from the result
+ * - Success(value) to use an alternate value
+ * - Failure to propagate the error
+ * @public
+ */
+export type ResourceErrorHandler = (resource: IResource, message: string, resolver: ResourceResolver) => Result<JsonValue | undefined>;
+/**
+ * Type for handling empty branch nodes during tree composition.
+ * The handler receives the branch node, names of failed children, and the resolver for recovery attempts.
+ * It can return:
+ * - Success(undefined) to omit the branch from the result
+ * - Success(value) to use an alternate value for the branch
+ * - Failure to propagate the error
+ * @public
+ */
+export type EmptyBranchHandler = (branchNode: IReadOnlyResourceTreeNode<IResource>, failedChildNames: string[], resolver: ResourceResolver) => Result<JsonValue | undefined>;
+/**
+ * Options for configuring resource tree resolution.
+ * @public
+ */
+export interface IResolveResourceTreeOptions {
+    /**
+     * Controls how errors are handled when resolving individual resources in the tree.
+     * - 'fail': Aggregate all errors and fail if any resource fails to resolve
+     * - 'ignore': Skip failed resources and omit them from the result
+     * - callback: Custom error handler that can provide alternate values or propagate errors
+     * @defaultValue 'fail'
+     */
+    onResourceError?: 'fail' | 'ignore' | ResourceErrorHandler;
+    /**
+     * Controls how empty branch nodes are handled during tree composition.
+     * - 'allow': Include empty branches as empty objects in the result
+     * - 'omit': Exclude empty branches from the parent object
+     * - callback: Custom handler that can provide alternate values or recovery logic
+     * @defaultValue 'allow'
+     */
+    onEmptyBranch?: 'allow' | 'omit' | EmptyBranchHandler;
+}
+/**
+ * Specialized resolver for resource tree operations, providing enhanced APIs for
+ * resolving entire resource trees from either resource IDs or pre-built tree nodes.
+ *
+ * This class provides a clean separation between individual resource resolution
+ * (handled by ResourceResolver) and tree-based operations, with support for
+ * lazy tree construction and enhanced error handling.
+ *
+ * @public
+ */
+export declare class ResourceTreeResolver {
+    /**
+     * The {@link Runtime.ResourceResolver | ResourceResolver} to use for individual resource resolution
+     */
+    readonly resolver: ResourceResolver;
+    /**
+     * The {@link Runtime.IResourceManager | IResourceManager} to use for lazy tree construction.
+     * @internal
+     */
+    private readonly _resourceManager;
+    /**
+     * The built resource tree, lazily built on first access.
+     * @internal
+     */
+    private _tree?;
+    /**
+     * Creates a {@link Runtime.ResourceTreeResolver | ResourceTreeResolver} instance.
+     * @param resolver - The ResourceResolver to use for individual resource resolution
+     */
+    constructor(resolver: ResourceResolver);
+    /**
+     * Creates a {@link Runtime.ResourceTreeResolver | ResourceTreeResolver} instance.
+     * @param resolver - The ResourceResolver to use for individual resource resolution
+     */
+    static create(resolver: ResourceResolver): Result<ResourceTreeResolver>;
+    /**
+     * Gets the built resource tree, building it lazily on first access.
+     * @returns The resource tree root
+     * @throws Error if no resource manager was provided or tree building fails
+     * @public
+     */
+    get tree(): IReadOnlyResourceTreeRoot<IResource>;
+    /**
+     * Resolves a resource tree from a resource ID, building the tree lazily from the resource manager.
+     * @param resourceId - The ID of the root resource to resolve
+     * @param options - Optional configuration for error handling during resolution
+     * @returns Success with the composed JsonObject or undefined, or Failure with error message
+     * @public
+     */
+    resolveComposedResourceTree(resourceId: string, options?: IResolveResourceTreeOptions): Result<JsonObject | undefined>;
+    /**
+     * Resolves a pre-built resource tree node.
+     * @param node - The resource tree node to resolve
+     * @param options - Optional configuration for error handling during resolution
+     * @returns Success with the composed JsonObject or undefined, or Failure with error message
+     * @public
+     */
+    resolveComposedResourceTree(node: IReadOnlyResourceTreeNode<IResource>, options?: IResolveResourceTreeOptions): Result<JsonObject | undefined>;
+    private _getTree;
+    /**
+     * Resolves a tree from a resource ID by first building the tree from the resource manager.
+     * @internal
+     */
+    private _resolveFromResourceId;
+    /**
+     * Resolves a pre-built tree node using the extracted tree resolution logic.
+     * @internal
+     */
+    private _resolveFromTreeNode;
+    /**
+     * Handles resource resolution errors according to the specified mode.
+     * @param resource - The resource that failed to resolve
+     * @param message - The error message from the failed resolution
+     * @param mode - The error handling mode
+     * @param path - The path to the resource in the tree (for error context)
+     * @internal
+     */
+    private _handleResourceError;
+    /**
+     * Handles empty branch nodes according to the specified mode.
+     * @param node - The empty branch node
+     * @param failedChildren - Names of children that failed to resolve
+     * @param mode - The empty branch handling mode
+     * @param path - The path to the branch in the tree (for error context)
+     * @internal
+     */
+    private _handleEmptyBranch;
+    /**
+     * Processes a leaf node by resolving its resource value.
+     * @param node - The leaf node to process (must be a leaf node)
+     * @param path - The path to the node in the tree
+     * @param resourceErrorMode - How to handle resource resolution errors
+     * @internal
+     */
+    private _processLeafNode;
+    /**
+     * Processes a branch node by recursively resolving all its children.
+     * @param node - The branch node to process (must be a branch node)
+     * @param path - The path to the node in the tree
+     * @param options - Resolution options
+     * @internal
+     */
+    private _processBranchNode;
+}
+//# sourceMappingURL=resourceTreeResolver.d.ts.map