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

package/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Change Log - @fgv/ts-res
+
+This log was last generated on Thu, 17 Jul 2025 00:13:24 GMT and should not be manually modified.
+
+## 5.0.0
+Thu, 17 Jul 2025 00:13:24 GMT
+
+### Updates
+
+- add decl generators
+- fix merge errors
+- flesh out tests
+- initial checkin
+

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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fgv/ts-res",
-  "version": "5.0.0-23",
+  "version": "5.0.0-24",
   "description": "Multi-dimensional Resource Runtime",
   "main": "lib/index.js",
   "types": "dist/ts-res.d.ts",
@@ -36,24 +36,24 @@
     "rimraf": "^5.0.7",
     "ts-jest": "^29.4.1",
     "ts-node": "^10.9.2",
-    "typescript": "^5.8.3",
+    "typescript": "5.8.3",
     "eslint-plugin-n": "^16.6.2",
-    "@rushstack/eslint-config": "~4.4.0",
-    "@rushstack/heft": "~0.74.2",
-    "@rushstack/heft-jest-plugin": "~0.16.11",
-    "@rushstack/heft-node-rig": "~2.9.3",
+    "@rushstack/eslint-config": "4.4.0",
+    "@rushstack/heft": "0.74.3",
+    "@rushstack/heft-jest-plugin": "0.16.12",
+    "@rushstack/heft-node-rig": "2.9.4",
     "@types/heft-jest": "1.0.6",
     "eslint-plugin-tsdoc": "~0.4.0",
-    "@fgv/ts-utils-jest": "5.0.0-23",
-    "@fgv/ts-extras": "5.0.0-23"
+    "@fgv/ts-utils-jest": "5.0.0-24",
+    "@fgv/ts-extras": "5.0.0-24"
   },
   "dependencies": {
     "luxon": "^3.7.1",
     "fflate": "~0.8.2",
-    "@fgv/ts-utils": "5.0.0-23",
-    "@fgv/ts-json-base": "5.0.0-23",
-    "@fgv/ts-json": "5.0.0-23",
-    "@fgv/ts-bcp47": "5.0.0-23"
+    "@fgv/ts-utils": "5.0.0-24",
+    "@fgv/ts-json-base": "5.0.0-24",
+    "@fgv/ts-json": "5.0.0-24",
+    "@fgv/ts-bcp47": "5.0.0-24"
   },
   "scripts": {
     "build": "heft build --clean",

package/.vscode/4.json

@@ -1,3 +0,0 @@
-{
-  "cSpell.words": ["fixlint", "luxon", "packlets", "rushstack", "rushx", "TINSTANCE", "xyzzy"]
-}

package/.vscode/launch.json

@@ -1,16 +0,0 @@
-{
-  // Use IntelliSense to learn about possible attributes.
-  // Hover to view descriptions of existing attributes.
-  // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
-  "version": "0.2.0",
-  "configurations": [
-    {
-      "type": "node",
-      "request": "launch",
-      "name": "Launch Program",
-      "skipFiles": ["<node_internals>/**"],
-      "program": "${workspaceFolder}/lib/index.js",
-      "outFiles": ["${workspaceFolder}/**/*.js"]
-    }
-  ]
-}

package/.vscode/settings.json

@@ -1,3 +0,0 @@
-{
-  "cSpell.words": ["importables"]
-}