@fgv/ts-res 4.5.0-3 → 5.0.0-2

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

@@ -0,0 +1,224 @@
+"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.ReadOnlyResourceTreeRoot = exports.ReadOnlyResourceTreeBranch = exports.ReadOnlyResourceTreeLeaf = void 0;
+exports.isResourceTreeRootOrNodeInit = isResourceTreeRootOrNodeInit;
+exports.isResourceTreeLeafInit = isResourceTreeLeafInit;
+const ts_utils_1 = require("@fgv/ts-utils");
+const common_1 = require("../../common");
+const resourceTreeChildren_1 = require("./resourceTreeChildren");
+// Type guards
+/**
+ * Type guard to determine if an init object represents a branch or root with children.
+ * @param init - The initialization object to test
+ * @returns True if the init object has children property
+ * @public
+ */
+function isResourceTreeRootOrNodeInit(init) {
+    return 'children' in init;
+}
+/**
+ * Type guard to determine if an init object represents a leaf node with a resource.
+ * @param init - The initialization object to test
+ * @returns True if the init object has a resource but no children
+ * @public
+ */
+function isResourceTreeLeafInit(init) {
+    return 'resource' in init && !('children' in init);
+}
+/**
+ * Implementation of a read-only resource tree leaf node that contains a resource value.
+ * Leaf nodes represent the actual resources in the tree and cannot have children.
+ * @public
+ */
+class ReadOnlyResourceTreeLeaf {
+    get isRoot() {
+        return false;
+    }
+    get isBranch() {
+        return false;
+    }
+    get isLeaf() {
+        return true;
+    }
+    /**
+     * Creates a new leaf node. Use the static create method instead.
+     * @param name - The name of this node (last segment of the path)
+     * @param parentPath - The path to the parent node (undefined for root-level nodes)
+     * @param resource - The resource value stored in this leaf
+     */
+    constructor(name, parentPath, resource) {
+        this.name = name;
+        this.id = common_1.Helpers.joinResourceIds(parentPath, name).orThrow();
+        this.resource = resource;
+    }
+    /**
+     * Creates a new ReadOnlyResourceTreeLeaf instance.
+     * @param name - The name of this node (last segment of the path)
+     * @param parentPath - The path to the parent node (undefined for root-level nodes)
+     * @param resource - The resource value to store in this leaf
+     * @returns Result containing the new leaf node or failure if construction fails
+     */
+    static create(name, parentPath, resource) {
+        return (0, ts_utils_1.captureResult)(() => new ReadOnlyResourceTreeLeaf(name, parentPath, resource));
+    }
+}
+exports.ReadOnlyResourceTreeLeaf = ReadOnlyResourceTreeLeaf;
+/**
+ * Implementation of a read-only resource tree branch node that contains child nodes.
+ * Branch nodes organize other nodes in a hierarchical structure and may optionally contain a resource value.
+ * @public
+ */
+class ReadOnlyResourceTreeBranch {
+    get isRoot() {
+        return false;
+    }
+    get isBranch() {
+        return true;
+    }
+    get isLeaf() {
+        return false;
+    }
+    /**
+     * Creates a new branch node. Use the static create method instead.
+     * @param name - The name of this node (last segment of the path)
+     * @param parentPath - The path to the parent node (undefined for root-level nodes)
+     * @param init - Initialization data containing child nodes
+     */
+    constructor(name, parentPath, init) {
+        this.name = name;
+        this.id = common_1.Helpers.joinResourceIds(parentPath, name).orThrow();
+        const children = (0, ts_utils_1.mapResults)(Array.from(Object.entries(init.children)).map(([childName, childInit]) => {
+            if (isResourceTreeLeafInit(childInit)) {
+                return ReadOnlyResourceTreeLeaf.create(childName, this.id, childInit.resource);
+            }
+            return ReadOnlyResourceTreeBranch.create(childName, this.id, childInit);
+        })).orThrow();
+        this.children = new resourceTreeChildren_1.ReadOnlyResourceTreeChildren(this.id, children.map((c) => [c.name, c]));
+    }
+    /**
+     * Creates a new ReadOnlyResourceTreeBranch instance.
+     * @param childName - The name of this node (last segment of the path)
+     * @param path - The path to the parent node (undefined for root-level nodes)
+     * @param childInit - Initialization data containing child nodes
+     * @returns Result containing the new branch node or failure if construction fails
+     */
+    static create(childName, path, childInit) {
+        return (0, ts_utils_1.captureResult)(() => new ReadOnlyResourceTreeBranch(childName, path, childInit));
+    }
+}
+exports.ReadOnlyResourceTreeBranch = ReadOnlyResourceTreeBranch;
+/**
+ * Implementation of a read-only resource tree root that organizes resources hierarchically.
+ * The root provides the entry point for tree navigation and resource access by ResourceId paths.
+ * @public
+ */
+class ReadOnlyResourceTreeRoot {
+    get isRoot() {
+        return true;
+    }
+    get isBranch() {
+        return false;
+    }
+    get isLeaf() {
+        return false;
+    }
+    /**
+     * Creates a new root node. Use the static create method instead.
+     * @param init - Initialization data containing child nodes
+     */
+    constructor(init) {
+        const children = (0, ts_utils_1.mapResults)(Array.from(Object.entries(init.children)).map(([childName, childInit]) => {
+            if (isResourceTreeLeafInit(childInit)) {
+                return ReadOnlyResourceTreeLeaf.create(childName, undefined, childInit.resource);
+            }
+            return ReadOnlyResourceTreeBranch.create(childName, undefined, childInit);
+        })).orThrow();
+        this.children = new resourceTreeChildren_1.ReadOnlyResourceTreeChildren(undefined, children.map((c) => [c.name, c]));
+    }
+    /**
+     * Creates a new ReadOnlyResourceTreeRoot from either resources or initialization data.
+     * @param init - Either an array of [ResourceId, resource] pairs or tree initialization structure
+     * @returns Result containing the new root or failure if construction fails
+     */
+    static create(init) {
+        if (Array.isArray(init)) {
+            return ReadOnlyResourceTreeRoot.createResourceTreeInit(init).onSuccess((treeInit) => (0, ts_utils_1.captureResult)(() => new ReadOnlyResourceTreeRoot(treeInit)));
+        }
+        return (0, ts_utils_1.captureResult)(() => new ReadOnlyResourceTreeRoot(init));
+    }
+    /**
+     * Converts an array of resources into tree initialization data.
+     * Validates that resource paths do not conflict - if a path has child resources,
+     * it cannot itself be a resource (e.g., if 'app.messages.welcome' exists, then 'app' cannot be a resource).
+     * @param resources - Array of [ResourceId, resource] pairs to convert
+     * @returns Result containing the initialization structure or failure if validation fails
+     */
+    static createResourceTreeInit(resources) {
+        const errors = new ts_utils_1.MessageAggregator();
+        const root = { children: {} };
+        for (const [id, resource] of resources) {
+            common_1.Helpers.splitResourceId(id)
+                .onSuccess((pathComponents) => {
+                let currentNode = root;
+                const resourceName = pathComponents.pop();
+                for (const nodeName of pathComponents) {
+                    if (isResourceTreeRootOrNodeInit(currentNode)) {
+                        if (!(nodeName in currentNode.children)) {
+                            currentNode.children[nodeName] = { children: {} };
+                        }
+                        if (isResourceTreeLeafInit(currentNode.children[nodeName])) {
+                            errors.addMessage(`${id}: Expected a branch but found a leaf at ${nodeName}.`);
+                        }
+                        else {
+                            currentNode = currentNode.children[nodeName];
+                        }
+                    } /* c8 ignore next 4 - defense in depth, not reachable without chicanery */
+                    else if (isResourceTreeLeafInit(currentNode)) {
+                        errors.addMessage(`${id}: Expected a branch but found a leaf.`);
+                        break;
+                    } /* c8 ignore next 3 - defense in depth, not reachable without chicanery */
+                    else {
+                        errors.addMessage(`${id}: Unexpected structure in resource tree`);
+                    }
+                }
+                if (isResourceTreeRootOrNodeInit(currentNode)) {
+                    if (resourceName in currentNode.children) {
+                        errors.addMessage(`${id}: Duplicate resource at path.`);
+                    }
+                    else {
+                        currentNode.children[resourceName] = { resource };
+                    } /* c8 ignore next 3 - defense in depth, not reachable without chicanery */
+                }
+                else {
+                    errors.addMessage(`${id}: Expected a branch but found a leaf.`);
+                }
+                return (0, ts_utils_1.succeed)(currentNode.children[resourceName]);
+            })
+                .aggregateError(errors);
+        }
+        return errors.returnOrReport((0, ts_utils_1.succeed)(root));
+    }
+}
+exports.ReadOnlyResourceTreeRoot = ReadOnlyResourceTreeRoot;
+//# sourceMappingURL=readOnlyResourceTree.js.map

package/lib/packlets/runtime/resource-tree/readOnlyResourceTree.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"readOnlyResourceTree.js","sourceRoot":"","sources":["../../../../src/packlets/runtime/resource-tree/readOnlyResourceTree.ts"],"names":[],"mappings":"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","sourcesContent":["/*\n * Copyright (c) 2025 Erik Fortune\n *\n * Permission is hereby granted, free of charge, to any person obtaining a copy\n * of this software and associated documentation files (the \"Software\"), to deal\n * in the Software without restriction, including without limitation the rights\n * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n * copies of the Software, and to permit persons to whom the Software is\n * furnished to do so, subject to the following conditions:\n *\n * The above copyright notice and this permission notice shall be included in all\n * copies or substantial portions of the Software.\n *\n * THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n * SOFTWARE.\n */\n\nimport { MessageAggregator, Result, captureResult, mapResults, succeed } from '@fgv/ts-utils';\nimport { ResourceId, ResourceName, Helpers } from '../../common';\nimport {\n  IReadOnlyResourceTreeNode,\n  IReadOnlyResourceTreeLeaf,\n  IReadOnlyResourceTreeBranch,\n  IReadOnlyResourceTreeRoot,\n  IReadOnlyValidatingResourceTreeChildren\n} from './common';\nimport { ReadOnlyResourceTreeChildren } from './resourceTreeChildren';\n\n/**\n * Interface for initializing a resource tree root with child nodes.\n * @public\n */\nexport interface IResourceTreeRootInit<T> {\n  readonly children: Record<ResourceName, ResourceTreeNodeInit<T>>;\n}\n\n/**\n * Interface for initializing a leaf node with a resource value.\n * @public\n */\nexport interface IResourceTreeLeafInit<T> {\n  readonly resource: T;\n}\n\n/**\n * Interface for initializing a branch node with child nodes.\n * @public\n */\nexport interface IResourceTreeBranchInit<T> {\n  readonly children: Record<ResourceName, ResourceTreeNodeInit<T>>;\n}\n\n/**\n * Union type for tree node initialization data.\n * @public\n */\nexport type ResourceTreeNodeInit<T> = IResourceTreeLeafInit<T> | IResourceTreeBranchInit<T>;\n\n// Type guards\n/**\n * Type guard to determine if an init object represents a branch or root with children.\n * @param init - The initialization object to test\n * @returns True if the init object has children property\n * @public\n */\nexport function isResourceTreeRootOrNodeInit<T>(\n  init: ResourceTreeNodeInit<T> | IResourceTreeRootInit<T>\n): init is IResourceTreeBranchInit<T> {\n  return 'children' in init;\n}\n\n/**\n * Type guard to determine if an init object represents a leaf node with a resource.\n * @param init - The initialization object to test\n * @returns True if the init object has a resource but no children\n * @public\n */\nexport function isResourceTreeLeafInit<T>(init: ResourceTreeNodeInit<T>): init is IResourceTreeLeafInit<T> {\n  return 'resource' in init && !('children' in init);\n}\n\n/**\n * Implementation of a read-only resource tree leaf node that contains a resource value.\n * Leaf nodes represent the actual resources in the tree and cannot have children.\n * @public\n */\nexport class ReadOnlyResourceTreeLeaf<T> implements IReadOnlyResourceTreeLeaf<T> {\n  public readonly name: ResourceName;\n  public readonly id: ResourceId;\n  public readonly resource: T;\n\n  public get isRoot(): false {\n    return false;\n  }\n\n  public get isBranch(): false {\n    return false;\n  }\n\n  public get isLeaf(): true {\n    return true;\n  }\n\n  /**\n   * Creates a new leaf node. Use the static create method instead.\n   * @param name - The name of this node (last segment of the path)\n   * @param parentPath - The path to the parent node (undefined for root-level nodes)\n   * @param resource - The resource value stored in this leaf\n   */\n  protected constructor(name: ResourceName, parentPath: ResourceId | undefined, resource: T) {\n    this.name = name;\n    this.id = Helpers.joinResourceIds(parentPath, name).orThrow();\n    this.resource = resource;\n  }\n\n  /**\n   * Creates a new ReadOnlyResourceTreeLeaf instance.\n   * @param name - The name of this node (last segment of the path)\n   * @param parentPath - The path to the parent node (undefined for root-level nodes)\n   * @param resource - The resource value to store in this leaf\n   * @returns Result containing the new leaf node or failure if construction fails\n   */\n  public static create<T>(\n    name: ResourceName,\n    parentPath: ResourceId | undefined,\n    resource: T\n  ): Result<ReadOnlyResourceTreeLeaf<T>> {\n    return captureResult(() => new ReadOnlyResourceTreeLeaf(name, parentPath, resource));\n  }\n}\n\n/**\n * Implementation of a read-only resource tree branch node that contains child nodes.\n * Branch nodes organize other nodes in a hierarchical structure and may optionally contain a resource value.\n * @public\n */\nexport class ReadOnlyResourceTreeBranch<T> implements IReadOnlyResourceTreeBranch<T> {\n  public readonly children: IReadOnlyValidatingResourceTreeChildren<T>;\n  public readonly name: ResourceName;\n  public readonly id: ResourceId;\n\n  public get isRoot(): false {\n    return false;\n  }\n\n  public get isBranch(): true {\n    return true;\n  }\n\n  public get isLeaf(): false {\n    return false;\n  }\n\n  /**\n   * Creates a new branch node. Use the static create method instead.\n   * @param name - The name of this node (last segment of the path)\n   * @param parentPath - The path to the parent node (undefined for root-level nodes)\n   * @param init - Initialization data containing child nodes\n   */\n  private constructor(\n    name: ResourceName,\n    parentPath: ResourceId | undefined,\n    init: IResourceTreeBranchInit<T>\n  ) {\n    this.name = name;\n    this.id = Helpers.joinResourceIds(parentPath, name).orThrow();\n\n    const children = mapResults<IReadOnlyResourceTreeNode<T>>(\n      (\n        Array.from(Object.entries(init.children)) as [\n          ResourceName,\n          IResourceTreeBranchInit<T> | IResourceTreeLeafInit<T>\n        ][]\n      ).map(([childName, childInit]) => {\n        if (isResourceTreeLeafInit(childInit)) {\n          return ReadOnlyResourceTreeLeaf.create(childName, this.id, childInit.resource);\n        }\n        return ReadOnlyResourceTreeBranch.create(childName, this.id, childInit);\n      })\n    ).orThrow();\n\n    this.children = new ReadOnlyResourceTreeChildren(\n      this.id,\n      children.map((c): [ResourceName, IReadOnlyResourceTreeNode<T>] => [c.name, c])\n    );\n  }\n\n  /**\n   * Creates a new ReadOnlyResourceTreeBranch instance.\n   * @param childName - The name of this node (last segment of the path)\n   * @param path - The path to the parent node (undefined for root-level nodes)\n   * @param childInit - Initialization data containing child nodes\n   * @returns Result containing the new branch node or failure if construction fails\n   */\n  public static create<T>(\n    childName: ResourceName,\n    path: ResourceId | undefined,\n    childInit: IResourceTreeBranchInit<T>\n  ): Result<ReadOnlyResourceTreeBranch<T>> {\n    return captureResult(() => new ReadOnlyResourceTreeBranch(childName, path, childInit));\n  }\n}\n\n/**\n * Union type representing any node in a read-only resource tree.\n * @public\n */\nexport type ReadOnlyResourceTreeNode<T> = ReadOnlyResourceTreeBranch<T> | ReadOnlyResourceTreeLeaf<T>;\n\n/**\n * Implementation of a read-only resource tree root that organizes resources hierarchically.\n * The root provides the entry point for tree navigation and resource access by ResourceId paths.\n * @public\n */\nexport class ReadOnlyResourceTreeRoot<T> implements IReadOnlyResourceTreeRoot<T> {\n  public readonly children: IReadOnlyValidatingResourceTreeChildren<T>;\n\n  public get isRoot(): true {\n    return true;\n  }\n\n  public get isBranch(): false {\n    return false;\n  }\n\n  public get isLeaf(): false {\n    return false;\n  }\n\n  /**\n   * Creates a new root node. Use the static create method instead.\n   * @param init - Initialization data containing child nodes\n   */\n  protected constructor(init: IResourceTreeRootInit<T>) {\n    const children = mapResults<ReadOnlyResourceTreeBranch<T> | ReadOnlyResourceTreeLeaf<T>>(\n      (\n        Array.from(Object.entries(init.children)) as [\n          ResourceName,\n          IResourceTreeBranchInit<T> | IResourceTreeLeafInit<T>\n        ][]\n      ).map(([childName, childInit]) => {\n        if (isResourceTreeLeafInit(childInit)) {\n          return ReadOnlyResourceTreeLeaf.create(childName, undefined, childInit.resource);\n        }\n        return ReadOnlyResourceTreeBranch.create(childName, undefined, childInit);\n      })\n    ).orThrow();\n\n    this.children = new ReadOnlyResourceTreeChildren(\n      undefined,\n      children.map((c): [ResourceName, IReadOnlyResourceTreeNode<T>] => [c.name, c])\n    );\n  }\n\n  /**\n   * Creates a new ReadOnlyResourceTreeRoot from an array of resources.\n   * @param resources - Array of [ResourceId, resource] pairs to build the tree from\n   * @returns Result containing the new root or failure if construction fails\n   */\n  public static create<T>(resources: [ResourceId, T][]): Result<ReadOnlyResourceTreeRoot<T>>;\n\n  /**\n   * Creates a new ReadOnlyResourceTreeRoot from initialization data.\n   * @param init - Tree initialization structure\n   * @returns Result containing the new root or failure if construction fails\n   */\n  public static create<T>(init: IResourceTreeRootInit<T>): Result<ReadOnlyResourceTreeRoot<T>>;\n\n  /**\n   * Creates a new ReadOnlyResourceTreeRoot from either resources or initialization data.\n   * @param init - Either an array of [ResourceId, resource] pairs or tree initialization structure\n   * @returns Result containing the new root or failure if construction fails\n   */\n  public static create<T>(\n    init: IResourceTreeRootInit<T> | [ResourceId, T][]\n  ): Result<ReadOnlyResourceTreeRoot<T>> {\n    if (Array.isArray(init)) {\n      return ReadOnlyResourceTreeRoot.createResourceTreeInit(init).onSuccess((treeInit) =>\n        captureResult(() => new ReadOnlyResourceTreeRoot(treeInit))\n      );\n    }\n    return captureResult(() => new ReadOnlyResourceTreeRoot(init));\n  }\n\n  /**\n   * Converts an array of resources into tree initialization data.\n   * Validates that resource paths do not conflict - if a path has child resources,\n   * it cannot itself be a resource (e.g., if 'app.messages.welcome' exists, then 'app' cannot be a resource).\n   * @param resources - Array of [ResourceId, resource] pairs to convert\n   * @returns Result containing the initialization structure or failure if validation fails\n   */\n  public static createResourceTreeInit<T>(resources: [ResourceId, T][]): Result<IResourceTreeRootInit<T>> {\n    const errors: MessageAggregator = new MessageAggregator();\n    const root: IResourceTreeRootInit<T> = { children: {} };\n\n    for (const [id, resource] of resources) {\n      Helpers.splitResourceId(id)\n        .onSuccess((pathComponents) => {\n          let currentNode: IResourceTreeBranchInit<T> | IResourceTreeRootInit<T> = root;\n          const resourceName = pathComponents.pop()!;\n\n          for (const nodeName of pathComponents) {\n            if (isResourceTreeRootOrNodeInit(currentNode)) {\n              if (!(nodeName in currentNode.children)) {\n                currentNode.children[nodeName] = { children: {} };\n              }\n              if (isResourceTreeLeafInit(currentNode.children[nodeName])) {\n                errors.addMessage(`${id}: Expected a branch but found a leaf at ${nodeName}.`);\n              } else {\n                currentNode = currentNode.children[nodeName];\n              }\n            } /* c8 ignore next 4 - defense in depth, not reachable without chicanery */ else if (\n              isResourceTreeLeafInit(currentNode)\n            ) {\n              errors.addMessage(`${id}: Expected a branch but found a leaf.`);\n              break;\n            } /* c8 ignore next 3 - defense in depth, not reachable without chicanery */ else {\n              errors.addMessage(`${id}: Unexpected structure in resource tree`);\n            }\n          }\n\n          if (isResourceTreeRootOrNodeInit(currentNode)) {\n            if (resourceName in currentNode.children) {\n              errors.addMessage(`${id}: Duplicate resource at path.`);\n            } else {\n              currentNode.children[resourceName] = { resource };\n            } /* c8 ignore next 3 - defense in depth, not reachable without chicanery */\n          } else {\n            errors.addMessage(`${id}: Expected a branch but found a leaf.`);\n          }\n          return succeed(currentNode.children[resourceName]);\n        })\n        .aggregateError(errors);\n    }\n    return errors.returnOrReport(succeed(root));\n  }\n}\n"]}

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

@@ -0,0 +1,24 @@
+import { Result, ResultMap } from '@fgv/ts-utils';
+import { ResourceId, ResourceName } from '../../common';
+import { IReadOnlyResourceTreeBranch, IReadOnlyResourceTreeChildren, IReadOnlyResourceTreeLeaf, IReadOnlyResourceTreeNode, IReadOnlyValidatingResourceTreeChildren } from './common';
+/**
+ * Implementation of a result-based resource tree that provides hierarchical access to resources.
+ * Extends ResultMap to provide collection-like access while adding tree-specific navigation methods.
+ * @public
+ */
+export declare class ReadOnlyResourceTreeChildren<T> extends ResultMap<ResourceName, IReadOnlyResourceTreeNode<T>> implements IReadOnlyValidatingResourceTreeChildren<T> {
+    protected path: ResourceId | undefined;
+    validating: IReadOnlyResourceTreeChildren<T, string, string>;
+    /**
+     * Creates a new ReadOnlyResourceTreeChildren instance.
+     * @param path - The path to this tree node (undefined for root)
+     * @param entries - Array of [name, node] tuples to populate the tree
+     */
+    constructor(path: ResourceId | undefined, entries: [ResourceName, IReadOnlyResourceTreeNode<T>][]);
+    getResource(name: ResourceName): Result<IReadOnlyResourceTreeNode<T>>;
+    getBranch(name: ResourceName): Result<IReadOnlyResourceTreeNode<T>>;
+    getById(id: ResourceId): Result<IReadOnlyResourceTreeNode<T>>;
+    getResourceById(id: ResourceId): Result<IReadOnlyResourceTreeLeaf<T>>;
+    getBranchById(id: ResourceId): Result<IReadOnlyResourceTreeBranch<T>>;
+}
+//# sourceMappingURL=resourceTreeChildren.d.ts.map

package/lib/packlets/runtime/resource-tree/resourceTreeChildren.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resourceTreeChildren.d.ts","sourceRoot":"","sources":["../../../../src/packlets/runtime/resource-tree/resourceTreeChildren.ts"],"names":[],"mappings":"AAsBA,OAAO,EAAe,MAAM,EAAE,SAAS,EAAiB,MAAM,eAAe,CAAC;AAC9E,OAAO,EAAE,UAAU,EAAE,YAAY,EAAW,MAAM,cAAc,CAAC;AACjE,OAAO,EACL,2BAA2B,EAC3B,6BAA6B,EAC7B,yBAAyB,EACzB,yBAAyB,EACzB,uCAAuC,EACxC,MAAM,UAAU,CAAC;AAGlB;;;;GAIG;AACH,qBAAa,4BAA4B,CAAC,CAAC,CACzC,SAAQ,SAAS,CAAC,YAAY,EAAE,yBAAyB,CAAC,CAAC,CAAC,CAC5D,YAAW,uCAAuC,CAAC,CAAC,CAAC;IAErD,SAAS,CAAC,IAAI,EAAE,UAAU,GAAG,SAAS,CAAC;IAChC,UAAU,EAAE,6BAA6B,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IAEpE;;;;OAIG;gBACgB,IAAI,EAAE,UAAU,GAAG,SAAS,EAAE,OAAO,EAAE,CAAC,YAAY,EAAE,yBAAyB,CAAC,CAAC,CAAC,CAAC,EAAE;IAMjG,WAAW,CAAC,IAAI,EAAE,YAAY,GAAG,MAAM,CAAC,yBAAyB,CAAC,CAAC,CAAC,CAAC;IAWrE,SAAS,CAAC,IAAI,EAAE,YAAY,GAAG,MAAM,CAAC,yBAAyB,CAAC,CAAC,CAAC,CAAC;IAWnE,OAAO,CAAC,EAAE,EAAE,UAAU,GAAG,MAAM,CAAC,yBAAyB,CAAC,CAAC,CAAC,CAAC;IAqB7D,eAAe,CAAC,EAAE,EAAE,UAAU,GAAG,MAAM,CAAC,yBAAyB,CAAC,CAAC,CAAC,CAAC;IAarE,aAAa,CAAC,EAAE,EAAE,UAAU,GAAG,MAAM,CAAC,2BAA2B,CAAC,CAAC,CAAC,CAAC;CAY7E"}

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

@@ -0,0 +1,98 @@
+"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.ReadOnlyResourceTreeChildren = void 0;
+const ts_utils_1 = require("@fgv/ts-utils");
+const common_1 = require("../../common");
+const resourceTreeChildrenValidator_1 = require("./resourceTreeChildrenValidator");
+/**
+ * Implementation of a result-based resource tree that provides hierarchical access to resources.
+ * Extends ResultMap to provide collection-like access while adding tree-specific navigation methods.
+ * @public
+ */
+class ReadOnlyResourceTreeChildren extends ts_utils_1.ResultMap {
+    /**
+     * Creates a new ReadOnlyResourceTreeChildren instance.
+     * @param path - The path to this tree node (undefined for root)
+     * @param entries - Array of [name, node] tuples to populate the tree
+     */
+    constructor(path, entries) {
+        super(entries);
+        this.path = path;
+        this.validating = new resourceTreeChildrenValidator_1.ResourceTreeChildrenValidator(this);
+    }
+    getResource(name) {
+        return this.get(name).onSuccess((node) => {
+            if (node.isLeaf) {
+                return (0, ts_utils_1.succeed)(node).withDetail('success');
+            }
+            return (0, ts_utils_1.fail)(`${name}: not a resource${this.path ? ` in ${this.path}` : ''}.`).withDetail('failure');
+        });
+    }
+    getBranch(name) {
+        return this.get(name).onSuccess((node) => {
+            if (node.isBranch) {
+                return (0, ts_utils_1.succeed)(node).withDetail('success');
+            }
+            return (0, ts_utils_1.fail)(`${name}: not a branch${this.path ? ` in ${this.path}` : ''}.`).withDetail('failure');
+        });
+    }
+    getById(id) {
+        return common_1.Helpers.splitResourceId(id).onSuccess((names) => {
+            let name = names.shift();
+            if (name !== undefined) {
+                let node = this.get(name).orDefault();
+                while (node) {
+                    name = names.shift();
+                    if (name === undefined) {
+                        return (0, ts_utils_1.succeed)(node);
+                    }
+                    if (node.isLeaf) {
+                        /* c8 ignore next 1 - defense in depth */
+                        return (0, ts_utils_1.fail)(`${id}: resource not found${this.path ? ` in ${this.path}` : ''}.`);
+                    }
+                    node = node.children.get(name).orDefault();
+                }
+            }
+            return (0, ts_utils_1.fail)(`${id}: resource not found${this.path ? ` in ${this.path}` : ''}.`);
+        });
+    }
+    getResourceById(id) {
+        return this.getById(id).onSuccess((node) => {
+            if (node.isLeaf) {
+                return (0, ts_utils_1.succeed)(node).withDetail('success');
+            }
+            return (0, ts_utils_1.fail)(`${id}: not a resource${this.path ? ` in ${this.path}` : ''}.`).withDetail('failure');
+        });
+    }
+    getBranchById(id) {
+        return this.getById(id).onSuccess((node) => {
+            if (node.isBranch) {
+                return (0, ts_utils_1.succeed)(node).withDetail('success');
+            }
+            return (0, ts_utils_1.fail)(`${id}: not a branch${this.path ? ` in ${this.path}` : ''}.`).withDetail('failure');
+        });
+    }
+}
+exports.ReadOnlyResourceTreeChildren = ReadOnlyResourceTreeChildren;
+//# sourceMappingURL=resourceTreeChildren.js.map

package/lib/packlets/runtime/resource-tree/resourceTreeChildren.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resourceTreeChildren.js","sourceRoot":"","sources":["../../../../src/packlets/runtime/resource-tree/resourceTreeChildren.ts"],"names":[],"mappings":"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","sourcesContent":["/*\n * Copyright (c) 2025 Erik Fortune\n *\n * Permission is hereby granted, free of charge, to any person obtaining a copy\n * of this software and associated documentation files (the \"Software\"), to deal\n * in the Software without restriction, including without limitation the rights\n * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n * copies of the Software, and to permit persons to whom the Software is\n * furnished to do so, subject to the following conditions:\n *\n * The above copyright notice and this permission notice shall be included in all\n * copies or substantial portions of the Software.\n *\n * THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n * SOFTWARE.\n */\n\nimport { Collections, Result, ResultMap, fail, succeed } from '@fgv/ts-utils';\nimport { ResourceId, ResourceName, Helpers } from '../../common';\nimport {\n  IReadOnlyResourceTreeBranch,\n  IReadOnlyResourceTreeChildren,\n  IReadOnlyResourceTreeLeaf,\n  IReadOnlyResourceTreeNode,\n  IReadOnlyValidatingResourceTreeChildren\n} from './common';\nimport { ResourceTreeChildrenValidator } from './resourceTreeChildrenValidator';\n\n/**\n * Implementation of a result-based resource tree that provides hierarchical access to resources.\n * Extends ResultMap to provide collection-like access while adding tree-specific navigation methods.\n * @public\n */\nexport class ReadOnlyResourceTreeChildren<T>\n  extends ResultMap<ResourceName, IReadOnlyResourceTreeNode<T>>\n  implements IReadOnlyValidatingResourceTreeChildren<T>\n{\n  protected path: ResourceId | undefined;\n  public validating: IReadOnlyResourceTreeChildren<T, string, string>;\n\n  /**\n   * Creates a new ReadOnlyResourceTreeChildren instance.\n   * @param path - The path to this tree node (undefined for root)\n   * @param entries - Array of [name, node] tuples to populate the tree\n   */\n  public constructor(path: ResourceId | undefined, entries: [ResourceName, IReadOnlyResourceTreeNode<T>][]) {\n    super(entries);\n    this.path = path;\n    this.validating = new ResourceTreeChildrenValidator<T>(this);\n  }\n\n  public getResource(name: ResourceName): Result<IReadOnlyResourceTreeNode<T>> {\n    return this.get(name).onSuccess((node) => {\n      if (node.isLeaf) {\n        return succeed(node).withDetail<Collections.ResultMapResultDetail>('success');\n      }\n      return fail<IReadOnlyResourceTreeNode<T>>(\n        `${name}: not a resource${this.path ? ` in ${this.path}` : ''}.`\n      ).withDetail<Collections.ResultMapResultDetail>('failure');\n    });\n  }\n\n  public getBranch(name: ResourceName): Result<IReadOnlyResourceTreeNode<T>> {\n    return this.get(name).onSuccess((node) => {\n      if (node.isBranch) {\n        return succeed(node).withDetail<Collections.ResultMapResultDetail>('success');\n      }\n      return fail<IReadOnlyResourceTreeNode<T>>(\n        `${name}: not a branch${this.path ? ` in ${this.path}` : ''}.`\n      ).withDetail<Collections.ResultMapResultDetail>('failure');\n    });\n  }\n\n  public getById(id: ResourceId): Result<IReadOnlyResourceTreeNode<T>> {\n    return Helpers.splitResourceId(id).onSuccess((names) => {\n      let name = names.shift();\n      if (name !== undefined) {\n        let node = this.get(name).orDefault();\n        while (node) {\n          name = names.shift();\n          if (name === undefined) {\n            return succeed(node);\n          }\n          if (node.isLeaf) {\n            /* c8 ignore next 1 - defense in depth */\n            return fail(`${id}: resource not found${this.path ? ` in ${this.path}` : ''}.`);\n          }\n          node = (node as IReadOnlyResourceTreeBranch<T>).children.get(name).orDefault();\n        }\n      }\n      return fail(`${id}: resource not found${this.path ? ` in ${this.path}` : ''}.`);\n    });\n  }\n\n  public getResourceById(id: ResourceId): Result<IReadOnlyResourceTreeLeaf<T>> {\n    return this.getById(id).onSuccess((node) => {\n      if (node.isLeaf) {\n        return succeed(node as IReadOnlyResourceTreeLeaf<T>).withDetail<Collections.ResultMapResultDetail>(\n          'success'\n        );\n      }\n      return fail<IReadOnlyResourceTreeLeaf<T>>(\n        `${id}: not a resource${this.path ? ` in ${this.path}` : ''}.`\n      ).withDetail<Collections.ResultMapResultDetail>('failure');\n    });\n  }\n\n  public getBranchById(id: ResourceId): Result<IReadOnlyResourceTreeBranch<T>> {\n    return this.getById(id).onSuccess((node) => {\n      if (node.isBranch) {\n        return succeed(node as IReadOnlyResourceTreeBranch<T>).withDetail<Collections.ResultMapResultDetail>(\n          'success'\n        );\n      }\n      return fail<IReadOnlyResourceTreeBranch<T>>(\n        `${id}: not a branch${this.path ? ` in ${this.path}` : ''}.`\n      ).withDetail<Collections.ResultMapResultDetail>('failure');\n    });\n  }\n}\n"]}

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

@@ -0,0 +1,99 @@
+import { Result, IReadOnlyResultMap, DetailedResult, Collections } from '@fgv/ts-utils';
+import { ResourceName } from '../../common';
+import { IReadOnlyResourceTreeBranch, IReadOnlyResourceTreeChildren, IReadOnlyResourceTreeLeaf, IReadOnlyResourceTreeNode } from './common';
+/**
+ * A validator wrapper for resource tree children that validates string inputs before
+ * delegating to the underlying tree children collection.
+ *
+ * This class implements {@link Runtime.ResourceTree.IReadOnlyValidatingResourceTreeChildren | IReadOnlyValidatingResourceTreeChildren}
+ * by wrapping an {@link Runtime.ResourceTree.IReadOnlyResourceTreeChildren | IReadOnlyResourceTreeChildren} instance and
+ * providing string-based access to all tree operations. All string inputs are validated using the library's
+ * validation utilities before being passed to the underlying collection.
+ *
+ * The validator acts as a bridge between string-based external APIs and the
+ * strongly-typed internal tree operations, ensuring type safety and consistent
+ * error handling throughout the resource tree navigation.
+ *
+ * @internal
+ */
+export declare class ResourceTreeChildrenValidator<T> implements IReadOnlyResourceTreeChildren<T, string, string> {
+    private readonly _inner;
+    /**
+     * Creates a new validator wrapper for resource tree children.
+     * @param inner - The underlying resource tree children collection to wrap with validation
+     */
+    constructor(inner: IReadOnlyResourceTreeChildren<T>);
+    /**
+     * Gets a tree node by its string ResourceId path, validating the input.
+     * @param id - The string ResourceId path to validate and look up
+     * @returns Result containing the node if found, or failure if validation fails or not found
+     */
+    getById(id: string): Result<IReadOnlyResourceTreeNode<T>>;
+    /**
+     * Gets a resource node by its string name (single component), validating the input.
+     * @param name - The string ResourceName to validate and look up
+     * @returns Result containing the node if it's a resource, or failure if validation fails or not found
+     */
+    getResource(name: string): Result<IReadOnlyResourceTreeNode<T>>;
+    /**
+     * Gets a branch node by its string name (single component), validating the input.
+     * @param name - The string ResourceName to validate and look up
+     * @returns Result containing the node if it's a branch, or failure if validation fails or not found
+     */
+    getBranch(name: string): Result<IReadOnlyResourceTreeNode<T>>;
+    /**
+     * Gets a resource leaf node by its string ResourceId path, validating the input.
+     * @param id - The string ResourceId path to validate and look up
+     * @returns Result containing the leaf if found and is a resource, or failure otherwise
+     */
+    getResourceById(id: string): Result<IReadOnlyResourceTreeLeaf<T>>;
+    /**
+     * Gets a branch node by its string ResourceId path, validating the input.
+     * @param id - The string ResourceId path to validate and look up
+     * @returns Result containing the branch if found and has children, or failure otherwise
+     */
+    getBranchById(id: string): Result<IReadOnlyResourceTreeBranch<T>>;
+    /**
+     * The number of direct child nodes in this collection.
+     */
+    get size(): number;
+    /**
+     * Returns an iterator of [ResourceName, node] pairs for all child nodes.
+     * @returns Map iterator for all child nodes
+     */
+    entries(): IterableIterator<[ResourceName, IReadOnlyResourceTreeNode<T>]>;
+    /**
+     * Executes a callback function for each child node in the collection.
+     * @param cb - The callback function to execute for each child node
+     * @param arg - Optional argument to pass to the callback
+     */
+    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
+     * @returns DetailedResult containing the node if found, or failure with details
+     */
+    get(key: ResourceName): DetailedResult<IReadOnlyResourceTreeNode<T>, Collections.ResultMapResultDetail>;
+    /**
+     * Checks if a child node exists at the given ResourceName key.
+     * @param key - The ResourceName key to check
+     * @returns True if a child node exists at the key, false otherwise
+     */
+    has(key: ResourceName): boolean;
+    /**
+     * Returns an iterator of ResourceName keys for all child nodes.
+     * @returns Map iterator for all child node keys
+     */
+    keys(): IterableIterator<ResourceName>;
+    /**
+     * Returns an iterator of child node values.
+     * @returns Map iterator for all child node values
+     */
+    values(): IterableIterator<IReadOnlyResourceTreeNode<T>>;
+    /**
+     * Returns an iterator for [ResourceName, node] pairs, enabling for...of iteration.
+     * @returns Iterable iterator for all child nodes
+     */
+    [Symbol.iterator](): IterableIterator<[ResourceName, IReadOnlyResourceTreeNode<T>]>;
+}
+//# sourceMappingURL=resourceTreeChildrenValidator.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"resourceTreeChildrenValidator.d.ts","sourceRoot":"","sources":["../../../../src/packlets/runtime/resource-tree/resourceTreeChildrenValidator.ts"],"names":[],"mappings":"AAuBA,OAAO,EAAE,MAAM,EAAE,kBAAkB,EAAE,cAAc,EAAE,WAAW,EAAkB,MAAM,eAAe,CAAC;AACxG,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,EACL,2BAA2B,EAC3B,6BAA6B,EAC7B,yBAAyB,EACzB,yBAAyB,EAC1B,MAAM,UAAU,CAAC;AAElB;;;;;;;;;;;;;;GAcG;AACH,qBAAa,6BAA6B,CAAC,CAAC,CAAE,YAAW,6BAA6B,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC;IACvG,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAmC;IAE1D;;;OAGG;gBACgB,KAAK,EAAE,6BAA6B,CAAC,CAAC,CAAC;IAI1D;;;;OAIG;IACI,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAAC,yBAAyB,CAAC,CAAC,CAAC,CAAC;IAMhE;;;;OAIG;IACI,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC,yBAAyB,CAAC,CAAC,CAAC,CAAC;IAMtE;;;;OAIG;IACI,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC,yBAAyB,CAAC,CAAC,CAAC,CAAC;IAMpE;;;;OAIG;IACI,eAAe,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAAC,yBAAyB,CAAC,CAAC,CAAC,CAAC;IAMxE;;;;OAIG;IACI,aAAa,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAAC,2BAA2B,CAAC,CAAC,CAAC,CAAC;IAMxE;;OAEG;IACH,IAAW,IAAI,IAAI,MAAM,CAExB;IAED;;;OAGG;IACI,OAAO,IAAI,gBAAgB,CAAC,CAAC,YAAY,EAAE,yBAAyB,CAAC,CAAC,CAAC,CAAC,CAAC;IAIhF;;;;OAIG;IACI,OAAO,CACZ,EAAE,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,kBAAkB,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,CAAC,EAAE,OAAO,KAAK,IAAI,EACtG,GAAG,CAAC,EAAE,OAAO,GACZ,IAAI;IAMP;;;;OAIG;IACI,GAAG,CACR,GAAG,EAAE,YAAY,GAChB,cAAc,CAAC,yBAAyB,CAAC,CAAC,CAAC,EAAE,WAAW,CAAC,qBAAqB,CAAC;IAOlF;;;;OAIG;IACI,GAAG,CAAC,GAAG,EAAE,YAAY,GAAG,OAAO;IAItC;;;OAGG;IACI,IAAI,IAAI,gBAAgB,CAAC,YAAY,CAAC;IAI7C;;;OAGG;IACI,MAAM,IAAI,gBAAgB,CAAC,yBAAyB,CAAC,CAAC,CAAC,CAAC;IAI/D;;;OAGG;IACI,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,gBAAgB,CAAC,CAAC,YAAY,EAAE,yBAAyB,CAAC,CAAC,CAAC,CAAC,CAAC;CAG3F"}