@fgv/ts-res 5.0.0-2 → 5.0.0-21

package/src/packlets/runtime/resource-tree/readOnlyResourceTree.ts

@@ -0,0 +1,342 @@
+/*
+ * 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.
+ */
+
+import { MessageAggregator, Result, captureResult, mapResults, succeed } from '@fgv/ts-utils';
+import { ResourceId, ResourceName, Helpers } from '../../common';
+import {
+  IReadOnlyResourceTreeNode,
+  IReadOnlyResourceTreeLeaf,
+  IReadOnlyResourceTreeBranch,
+  IReadOnlyResourceTreeRoot,
+  IReadOnlyValidatingResourceTreeChildren
+} from './common';
+import { ReadOnlyResourceTreeChildren } from './resourceTreeChildren';
+
+/**
+ * Interface for initializing a resource tree root with child nodes.
+ * @public
+ */
+export interface IResourceTreeRootInit<T> {
+  readonly children: Record<ResourceName, ResourceTreeNodeInit<T>>;
+}
+
+/**
+ * Interface for initializing a leaf node with a resource value.
+ * @public
+ */
+export interface IResourceTreeLeafInit<T> {
+  readonly resource: T;
+}
+
+/**
+ * Interface for initializing a branch node with child nodes.
+ * @public
+ */
+export interface IResourceTreeBranchInit<T> {
+  readonly children: Record<ResourceName, ResourceTreeNodeInit<T>>;
+}
+
+/**
+ * Union type for tree node initialization data.
+ * @public
+ */
+export type ResourceTreeNodeInit<T> = IResourceTreeLeafInit<T> | IResourceTreeBranchInit<T>;
+
+// 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
+ */
+export function isResourceTreeRootOrNodeInit<T>(
+  init: ResourceTreeNodeInit<T> | IResourceTreeRootInit<T>
+): init is IResourceTreeBranchInit<T> {
+  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
+ */
+export function isResourceTreeLeafInit<T>(init: ResourceTreeNodeInit<T>): init is IResourceTreeLeafInit<T> {
+  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
+ */
+export class ReadOnlyResourceTreeLeaf<T> implements IReadOnlyResourceTreeLeaf<T> {
+  public readonly name: ResourceName;
+  public readonly id: ResourceId;
+  public readonly resource: T;
+
+  public get isRoot(): false {
+    return false;
+  }
+
+  public get isBranch(): false {
+    return false;
+  }
+
+  public get isLeaf(): true {
+    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
+   */
+  protected constructor(name: ResourceName, parentPath: ResourceId | undefined, resource: T) {
+    this.name = name;
+    this.id = 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
+   */
+  public static create<T>(
+    name: ResourceName,
+    parentPath: ResourceId | undefined,
+    resource: T
+  ): Result<ReadOnlyResourceTreeLeaf<T>> {
+    return captureResult(() => new ReadOnlyResourceTreeLeaf(name, parentPath, resource));
+  }
+}
+
+/**
+ * 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
+ */
+export class ReadOnlyResourceTreeBranch<T> implements IReadOnlyResourceTreeBranch<T> {
+  public readonly children: IReadOnlyValidatingResourceTreeChildren<T>;
+  public readonly name: ResourceName;
+  public readonly id: ResourceId;
+
+  public get isRoot(): false {
+    return false;
+  }
+
+  public get isBranch(): true {
+    return true;
+  }
+
+  public get isLeaf(): false {
+    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
+   */
+  private constructor(
+    name: ResourceName,
+    parentPath: ResourceId | undefined,
+    init: IResourceTreeBranchInit<T>
+  ) {
+    this.name = name;
+    this.id = Helpers.joinResourceIds(parentPath, name).orThrow();
+
+    const children = mapResults<IReadOnlyResourceTreeNode<T>>(
+      (
+        Array.from(Object.entries(init.children)) as [
+          ResourceName,
+          IResourceTreeBranchInit<T> | IResourceTreeLeafInit<T>
+        ][]
+      ).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 ReadOnlyResourceTreeChildren(
+      this.id,
+      children.map((c): [ResourceName, IReadOnlyResourceTreeNode<T>] => [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
+   */
+  public static create<T>(
+    childName: ResourceName,
+    path: ResourceId | undefined,
+    childInit: IResourceTreeBranchInit<T>
+  ): Result<ReadOnlyResourceTreeBranch<T>> {
+    return captureResult(() => new ReadOnlyResourceTreeBranch(childName, path, childInit));
+  }
+}
+
+/**
+ * Union type representing any node in a read-only resource tree.
+ * @public
+ */
+export type ReadOnlyResourceTreeNode<T> = ReadOnlyResourceTreeBranch<T> | ReadOnlyResourceTreeLeaf<T>;
+
+/**
+ * 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
+ */
+export class ReadOnlyResourceTreeRoot<T> implements IReadOnlyResourceTreeRoot<T> {
+  public readonly children: IReadOnlyValidatingResourceTreeChildren<T>;
+
+  public get isRoot(): true {
+    return true;
+  }
+
+  public get isBranch(): false {
+    return false;
+  }
+
+  public get isLeaf(): false {
+    return false;
+  }
+
+  /**
+   * Creates a new root node. Use the static create method instead.
+   * @param init - Initialization data containing child nodes
+   */
+  protected constructor(init: IResourceTreeRootInit<T>) {
+    const children = mapResults<ReadOnlyResourceTreeBranch<T> | ReadOnlyResourceTreeLeaf<T>>(
+      (
+        Array.from(Object.entries(init.children)) as [
+          ResourceName,
+          IResourceTreeBranchInit<T> | IResourceTreeLeafInit<T>
+        ][]
+      ).map(([childName, childInit]) => {
+        if (isResourceTreeLeafInit(childInit)) {
+          return ReadOnlyResourceTreeLeaf.create(childName, undefined, childInit.resource);
+        }
+        return ReadOnlyResourceTreeBranch.create(childName, undefined, childInit);
+      })
+    ).orThrow();
+
+    this.children = new ReadOnlyResourceTreeChildren(
+      undefined,
+      children.map((c): [ResourceName, IReadOnlyResourceTreeNode<T>] => [c.name, c])
+    );
+  }
+
+  /**
+   * Creates a new ReadOnlyResourceTreeRoot from an array of resources.
+   * @param resources - Array of [ResourceId, resource] pairs to build the tree from
+   * @returns Result containing the new root or failure if construction fails
+   */
+  public static create<T>(resources: [ResourceId, T][]): Result<ReadOnlyResourceTreeRoot<T>>;
+
+  /**
+   * Creates a new ReadOnlyResourceTreeRoot from initialization data.
+   * @param init - Tree initialization structure
+   * @returns Result containing the new root or failure if construction fails
+   */
+  public static create<T>(init: IResourceTreeRootInit<T>): Result<ReadOnlyResourceTreeRoot<T>>;
+
+  /**
+   * 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
+   */
+  public static create<T>(
+    init: IResourceTreeRootInit<T> | [ResourceId, T][]
+  ): Result<ReadOnlyResourceTreeRoot<T>> {
+    if (Array.isArray(init)) {
+      return ReadOnlyResourceTreeRoot.createResourceTreeInit(init).onSuccess((treeInit) =>
+        captureResult(() => new ReadOnlyResourceTreeRoot(treeInit))
+      );
+    }
+    return 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
+   */
+  public static createResourceTreeInit<T>(resources: [ResourceId, T][]): Result<IResourceTreeRootInit<T>> {
+    const errors: MessageAggregator = new MessageAggregator();
+    const root: IResourceTreeRootInit<T> = { children: {} };
+
+    for (const [id, resource] of resources) {
+      Helpers.splitResourceId(id)
+        .onSuccess((pathComponents) => {
+          let currentNode: IResourceTreeBranchInit<T> | IResourceTreeRootInit<T> = 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 succeed(currentNode.children[resourceName]);
+        })
+        .aggregateError(errors);
+    }
+    return errors.returnOrReport(succeed(root));
+  }
+}

package/src/packlets/runtime/resource-tree/resourceTreeChildren.ts

@@ -0,0 +1,125 @@
+/*
+ * 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.
+ */
+
+import { Collections, Result, ResultMap, fail, succeed } from '@fgv/ts-utils';
+import { ResourceId, ResourceName, Helpers } from '../../common';
+import {
+  IReadOnlyResourceTreeBranch,
+  IReadOnlyResourceTreeChildren,
+  IReadOnlyResourceTreeLeaf,
+  IReadOnlyResourceTreeNode,
+  IReadOnlyValidatingResourceTreeChildren
+} from './common';
+import { ResourceTreeChildrenValidator } from './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
+ */
+export class ReadOnlyResourceTreeChildren<T>
+  extends ResultMap<ResourceName, IReadOnlyResourceTreeNode<T>>
+  implements IReadOnlyValidatingResourceTreeChildren<T>
+{
+  protected path: ResourceId | undefined;
+  public 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
+   */
+  public constructor(path: ResourceId | undefined, entries: [ResourceName, IReadOnlyResourceTreeNode<T>][]) {
+    super(entries);
+    this.path = path;
+    this.validating = new ResourceTreeChildrenValidator<T>(this);
+  }
+
+  public getResource(name: ResourceName): Result<IReadOnlyResourceTreeNode<T>> {
+    return this.get(name).onSuccess((node) => {
+      if (node.isLeaf) {
+        return succeed(node).withDetail<Collections.ResultMapResultDetail>('success');
+      }
+      return fail<IReadOnlyResourceTreeNode<T>>(
+        `${name}: not a resource${this.path ? ` in ${this.path}` : ''}.`
+      ).withDetail<Collections.ResultMapResultDetail>('failure');
+    });
+  }
+
+  public getBranch(name: ResourceName): Result<IReadOnlyResourceTreeNode<T>> {
+    return this.get(name).onSuccess((node) => {
+      if (node.isBranch) {
+        return succeed(node).withDetail<Collections.ResultMapResultDetail>('success');
+      }
+      return fail<IReadOnlyResourceTreeNode<T>>(
+        `${name}: not a branch${this.path ? ` in ${this.path}` : ''}.`
+      ).withDetail<Collections.ResultMapResultDetail>('failure');
+    });
+  }
+
+  public getById(id: ResourceId): Result<IReadOnlyResourceTreeNode<T>> {
+    return 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 succeed(node);
+          }
+          if (node.isLeaf) {
+            /* c8 ignore next 1 - defense in depth */
+            return fail(`${id}: resource not found${this.path ? ` in ${this.path}` : ''}.`);
+          }
+          node = (node as IReadOnlyResourceTreeBranch<T>).children.get(name).orDefault();
+        }
+      }
+      return fail(`${id}: resource not found${this.path ? ` in ${this.path}` : ''}.`);
+    });
+  }
+
+  public getResourceById(id: ResourceId): Result<IReadOnlyResourceTreeLeaf<T>> {
+    return this.getById(id).onSuccess((node) => {
+      if (node.isLeaf) {
+        return succeed(node as IReadOnlyResourceTreeLeaf<T>).withDetail<Collections.ResultMapResultDetail>(
+          'success'
+        );
+      }
+      return fail<IReadOnlyResourceTreeLeaf<T>>(
+        `${id}: not a resource${this.path ? ` in ${this.path}` : ''}.`
+      ).withDetail<Collections.ResultMapResultDetail>('failure');
+    });
+  }
+
+  public getBranchById(id: ResourceId): Result<IReadOnlyResourceTreeBranch<T>> {
+    return this.getById(id).onSuccess((node) => {
+      if (node.isBranch) {
+        return succeed(node as IReadOnlyResourceTreeBranch<T>).withDetail<Collections.ResultMapResultDetail>(
+          'success'
+        );
+      }
+      return fail<IReadOnlyResourceTreeBranch<T>>(
+        `${id}: not a branch${this.path ? ` in ${this.path}` : ''}.`
+      ).withDetail<Collections.ResultMapResultDetail>('failure');
+    });
+  }
+}

package/src/packlets/runtime/resource-tree/resourceTreeChildrenValidator.ts

@@ -0,0 +1,187 @@
+/*
+ * 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.
+ */
+
+import { Validate } from '../../common';
+import { Result, IReadOnlyResultMap, DetailedResult, Collections, failWithDetail } 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.
+ *
+ * @public
+ */
+export class ResourceTreeChildrenValidator<T> implements IReadOnlyResourceTreeChildren<T, string, string> {
+  private readonly _inner: IReadOnlyResourceTreeChildren<T>;
+
+  /**
+   * Creates a new validator wrapper for resource tree children.
+   * @param inner - The underlying resource tree children collection to wrap with validation
+   */
+  public constructor(inner: IReadOnlyResourceTreeChildren<T>) {
+    this._inner = inner;
+  }
+
+  /**
+   * 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
+   */
+  public getById(id: string): Result<IReadOnlyResourceTreeNode<T>> {
+    return Validate.toResourceId(id).onSuccess((resourceId) => {
+      return this._inner.getById(resourceId);
+    });
+  }
+
+  /**
+   * 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
+   */
+  public getResource(name: string): Result<IReadOnlyResourceTreeNode<T>> {
+    return Validate.toResourceName(name).onSuccess((resourceName) => {
+      return this._inner.getResource(resourceName);
+    });
+  }
+
+  /**
+   * 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
+   */
+  public getBranch(name: string): Result<IReadOnlyResourceTreeNode<T>> {
+    return Validate.toResourceName(name).onSuccess((resourceName) => {
+      return this._inner.getBranch(resourceName);
+    });
+  }
+
+  /**
+   * 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
+   */
+  public getResourceById(id: string): Result<IReadOnlyResourceTreeLeaf<T>> {
+    return Validate.toResourceId(id).onSuccess((resourceId) => {
+      return this._inner.getResourceById(resourceId);
+    });
+  }
+
+  /**
+   * 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
+   */
+  public getBranchById(id: string): Result<IReadOnlyResourceTreeBranch<T>> {
+    return Validate.toResourceId(id).onSuccess((resourceId) => {
+      return this._inner.getBranchById(resourceId);
+    });
+  }
+
+  /**
+   * The number of direct child nodes in this collection.
+   */
+  public get size(): number {
+    return this._inner.size;
+  }
+
+  /**
+   * Returns an iterator of [ResourceName, node] pairs for all child nodes.
+   * @returns Map iterator for all child nodes
+   */
+  public entries(): IterableIterator<[ResourceName, IReadOnlyResourceTreeNode<T>]> {
+    return this._inner.entries();
+  }
+
+  /**
+   * 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
+   */
+  public forEach(
+    cb: (value: unknown, key: string, map: IReadOnlyResultMap<string, unknown>, thisArg?: unknown) => void,
+    arg?: unknown
+  ): void {
+    for (const [key, value] of this._inner.entries()) {
+      cb(value, key as ResourceName, this, arg);
+    }
+  }
+
+  /**
+   * Gets a child node by its string key with detailed error information.
+   * @param key - The string key to look up
+   * @returns DetailedResult containing the node if found, or failure with details
+   */
+  public get(key: string): DetailedResult<IReadOnlyResourceTreeNode<T>, Collections.ResultMapResultDetail> {
+    if (Validate.isValidResourceName(key)) {
+      return this._inner.get(key);
+    }
+    return failWithDetail(`${key}: invalid resource name.`, 'invalid-key');
+  }
+
+  /**
+   * Checks if a child node exists at the given string key.
+   * @param key - The string key to check
+   * @returns True if a child node exists at the key, false otherwise
+   */
+  public has(key: string): boolean {
+    return this._inner.has(key as ResourceName);
+  }
+
+  /**
+   * Returns an iterator of ResourceName keys for all child nodes.
+   * @returns Map iterator for all child node keys
+   */
+  public keys(): IterableIterator<ResourceName> {
+    return this._inner.keys();
+  }
+
+  /**
+   * Returns an iterator of child node values.
+   * @returns Map iterator for all child node values
+   */
+  public values(): IterableIterator<IReadOnlyResourceTreeNode<T>> {
+    return this._inner.values();
+  }
+
+  /**
+   * Returns an iterator for [ResourceName, node] pairs, enabling for...of iteration.
+   * @returns Iterable iterator for all child nodes
+   */
+  public [Symbol.iterator](): IterableIterator<[ResourceName, IReadOnlyResourceTreeNode<T>]> {
+    return this._inner[Symbol.iterator]();
+  }
+}