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

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}`);
             }
@@ -223,8 +238,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}`);
             }
@@ -260,15 +275,13 @@ 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) {
+        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 +306,13 @@ 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) {
+        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 +348,13 @@ 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) {
+        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 +378,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 +403,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 +415,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

package/lib/packlets/runtime/resourceTreeResolver.js

@@ -0,0 +1,222 @@
+"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.ResourceTreeResolver = void 0;
+const ts_utils_1 = require("@fgv/ts-utils");
+const ts_json_base_1 = require("@fgv/ts-json-base");
+/**
+ * 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
+ */
+class ResourceTreeResolver {
+    /**
+     * Creates a {@link Runtime.ResourceTreeResolver | ResourceTreeResolver} instance.
+     * @param resolver - The ResourceResolver to use for individual resource resolution
+     */
+    constructor(resolver) {
+        this.resolver = resolver;
+        this._resourceManager = resolver.resourceManager;
+    }
+    /**
+     * Creates a {@link Runtime.ResourceTreeResolver | ResourceTreeResolver} instance.
+     * @param resolver - The ResourceResolver to use for individual resource resolution
+     */
+    static create(resolver) {
+        return (0, ts_utils_1.captureResult)(() => new ResourceTreeResolver(resolver));
+    }
+    /**
+     * 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() {
+        return this._getTree().orThrow();
+    }
+    /**
+     * Implementation for both overloads.
+     */
+    resolveComposedResourceTree(idOrNode, options) {
+        if (typeof idOrNode === 'string') {
+            return this._resolveFromResourceId(idOrNode, options);
+        }
+        return this._resolveFromTreeNode(idOrNode, options);
+    }
+    _getTree() {
+        if (!this._tree) {
+            this._tree = this._resourceManager.getBuiltResourceTree();
+        }
+        return this._tree;
+    }
+    /**
+     * Resolves a tree from a resource ID by first building the tree from the resource manager.
+     * @internal
+     */
+    _resolveFromResourceId(resourceId, options) {
+        return this._getTree().onSuccess((tree) => {
+            return tree.children.validating
+                .getById(resourceId)
+                .onFailure((message) => (0, ts_utils_1.fail)(`${resourceId}: Resource not found in resource tree: ${message}`))
+                .onSuccess((rootNode) => this._resolveFromTreeNode(rootNode, options));
+        });
+    }
+    /**
+     * Resolves a pre-built tree node using the extracted tree resolution logic.
+     * @internal
+     */
+    _resolveFromTreeNode(node, options) {
+        var _a, _b;
+        const resourceErrorMode = (_a = options === null || options === void 0 ? void 0 : options.onResourceError) !== null && _a !== void 0 ? _a : 'fail';
+        const emptyBranchMode = (_b = options === null || options === void 0 ? void 0 : options.onEmptyBranch) !== null && _b !== void 0 ? _b : 'allow';
+        // Handle root node with proper Result chaining
+        return node.isLeaf
+            ? this._processLeafNode(node, '', resourceErrorMode).onSuccess((value) => value !== undefined ? ts_json_base_1.Converters.jsonObject.convert(value) : (0, ts_utils_1.succeed)(undefined))
+            : this._processBranchNode(node, '', {
+                onResourceError: resourceErrorMode,
+                onEmptyBranch: emptyBranchMode
+            }).onSuccess((value) => {
+                // Only convert undefined to {} if emptyBranchMode is 'allow'
+                // For 'omit' mode or custom handlers returning undefined, preserve undefined
+                return (0, ts_utils_1.succeed)(value === undefined && emptyBranchMode === 'allow' ? {} : value);
+            });
+    }
+    /**
+     * 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
+     */
+    _handleResourceError(resource, message, mode, path) {
+        if (mode === 'ignore') {
+            return (0, ts_utils_1.succeed)(undefined);
+        }
+        if (mode === 'fail') {
+            const errorMessage = path ? `${path}: ${message}` : message;
+            return (0, ts_utils_1.fail)(errorMessage);
+        }
+        // Custom handler - pass the resolver for recovery attempts
+        return mode(resource, message, this.resolver);
+    }
+    /**
+     * 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
+     */
+    _handleEmptyBranch(node, failedChildren, mode, path) {
+        if (mode === 'omit') {
+            return (0, ts_utils_1.succeed)(undefined);
+        }
+        if (mode === 'allow') {
+            return (0, ts_utils_1.succeed)({});
+        }
+        // Custom handler - pass the resolver for recovery attempts
+        return mode(node, failedChildren, this.resolver);
+    }
+    /**
+     * 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
+     */
+    _processLeafNode(node, path, resourceErrorMode) {
+        /* c8 ignore next 3 - defense in depth */
+        if (!node.isLeaf) {
+            return (0, ts_utils_1.fail)(`Internal error: processLeafNode called on non-leaf node at ${path}`);
+        }
+        return this.resolver
+            .resolveComposedResourceValue(node.resource)
+            .onSuccess((value) => (0, ts_utils_1.succeed)(value))
+            .onFailure((message) => this._handleResourceError(node.resource, message, resourceErrorMode, path));
+    }
+    /**
+     * 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
+     */
+    _processBranchNode(node, path, options) {
+        var _a, _b;
+        /* c8 ignore next 3 - defense in depth */
+        if (node.isLeaf) {
+            return (0, ts_utils_1.fail)(`Internal error: processBranchNode called on leaf node at ${path}`);
+        }
+        const resourceErrorMode = (_a = options.onResourceError) !== null && _a !== void 0 ? _a : 'fail';
+        const emptyBranchMode = (_b = options.onEmptyBranch) !== null && _b !== void 0 ? _b : 'allow';
+        const aggregator = new ts_utils_1.MessageAggregator();
+        // Process all children
+        const childResults = {};
+        const failedChildren = [];
+        for (const [childName, childNode] of node.children) {
+            const childPath = path ? `${path}.${childName}` : childName;
+            const childResult = childNode.isLeaf
+                ? this._processLeafNode(childNode, childPath, resourceErrorMode)
+                : this._processBranchNode(childNode, childPath, options);
+            // Process the child result and update our state
+            if (childResult.isSuccess()) {
+                const value = childResult.value;
+                if (value !== undefined) {
+                    childResults[childName] = value;
+                }
+                else {
+                    failedChildren.push(childName);
+                }
+            }
+            else {
+                if (resourceErrorMode === 'fail') {
+                    aggregator.addMessage(childResult.message);
+                }
+                failedChildren.push(childName);
+            }
+        }
+        // Check for accumulated errors in 'fail' mode
+        if (resourceErrorMode === 'fail' && aggregator.hasMessages) {
+            return (0, ts_utils_1.fail)(aggregator.toString('; '));
+        }
+        // Handle empty branch
+        if (Object.keys(childResults).length === 0) {
+            return this._handleEmptyBranch(node, failedChildren, emptyBranchMode, path).onSuccess((value) => {
+                if (value === undefined) {
+                    return (0, ts_utils_1.succeed)(undefined);
+                }
+                // Ensure we return JsonObject or undefined
+                return ts_json_base_1.Converters.jsonObject.convert(value);
+            });
+        }
+        return (0, ts_utils_1.succeed)(childResults);
+    }
+}
+exports.ResourceTreeResolver = ResourceTreeResolver;
+//# sourceMappingURL=resourceTreeResolver.js.map

package/lib/packlets/runtime/validate.js

@@ -42,6 +42,7 @@ exports.resourceCandidate = ts_utils_1.Validators.object({
  */
 exports.resource = ts_utils_1.Validators.object({
     id: ts_utils_1.Validators.isA('ResourceId', (v) => typeof v === 'string' && common_1.Validate.isValidResourceId(v)),
+    name: ts_utils_1.Validators.isA('ResourceName', (v) => typeof v === 'string' && common_1.Validate.isValidResourceName(v)),
     resourceType: ts_utils_1.Validators.isA('ResourceType instance', (v) => v instanceof resource_types_1.ResourceType),
     decision: ts_utils_1.Validators.isA('ConcreteDecision instance', (v) => v instanceof decisions_1.ConcreteDecision),
     candidates: ts_utils_1.Validators.arrayOf(exports.resourceCandidate)

package/lib/packlets/zip-archive/convert.d.ts

@@ -0,0 +1,52 @@
+import { Validator, Converter } from '@fgv/ts-utils';
+import * as Json from './json';
+import { Model as ConfigModel } from '../config';
+/**
+ * Validator for ZIP archive input type
+ * @public
+ */
+export declare const zipArchiveInputType: Validator<'file' | 'directory'>;
+/**
+ * Validator for ZIP archive config type
+ * @public
+ */
+export declare const zipArchiveConfigType: Validator<'file'>;
+/**
+ * Validator for ZIP archive input information
+ * @public
+ */
+export declare const zipArchiveInputInfo: Validator<Json.IZipArchiveInputInfo>;
+/**
+ * Validator for ZIP archive config information
+ * @public
+ */
+export declare const zipArchiveConfigInfo: Validator<Json.IZipArchiveConfigInfo>;
+/**
+ * Validator for ZIP archive manifest
+ * Compatible with existing tools from ts-res-browser-cli
+ * @public
+ */
+export declare const zipArchiveManifest: Validator<Json.IZipArchiveManifest>;
+/**
+ * Validator for MIME type strings
+ * @public
+ */
+export declare const mimeType: Validator<string>;
+/**
+ * Converter for imported file
+ * @public
+ */
+export declare const importedFile: Converter<Json.IImportedFile>;
+/**
+ * Converter for imported directory structure (recursive)
+ * Note: Uses Converter pattern because Validators don't support recursion with self parameter
+ * @public
+ */
+export declare const importedDirectory: Converter<Json.IImportedDirectory>;
+/**
+ * Validator for system configuration (delegates to config packlet)
+ * This validates that the parsed JSON conforms to the system configuration schema
+ * @public
+ */
+export declare const systemConfiguration: Validator<ConfigModel.ISystemConfiguration>;
+//# sourceMappingURL=convert.d.ts.map