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

package/src/packlets/runtime/context/simpleContextQualifierProvider.ts

@@ -0,0 +1,225 @@
+/*
+ * 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 { Result, ResultMap, captureResult, succeed, fail, succeedWithDetail } from '@fgv/ts-utils';
+import { QualifierName, QualifierContextValue, QualifierIndex, Validate } from '../../common';
+import { IReadOnlyQualifierCollector, Qualifier } from '../../qualifiers';
+import { ContextQualifierProvider } from './contextQualifierProvider';
+
+/**
+ * Parameters for creating a {@link Runtime.SimpleContextQualifierProvider | SimpleContextQualifierProvider}.
+ * @public
+ */
+export interface ISimpleContextQualifierProviderCreateParams {
+  /**
+   * The {@link Qualifiers.IReadOnlyQualifierCollector | readonly qualifier collector} that defines and validates qualifiers.
+   */
+  qualifiers: IReadOnlyQualifierCollector;
+
+  /**
+   * Optional record of initial qualifier name-value pairs to populate the provider.
+   */
+  qualifierValues?: Record<string, QualifierContextValue>;
+}
+
+/**
+ * Simple concrete implementation of {@link Runtime.Context.IContextQualifierProvider | IContextQualifierProvider}
+ * using a `ResultMap` for qualifier value storage.
+ * @public
+ */
+export class SimpleContextQualifierProvider extends ContextQualifierProvider {
+  /**
+   * The readonly qualifier collector that defines and validates the qualifiers for this context.
+   */
+  public readonly qualifiers: IReadOnlyQualifierCollector;
+
+  /**
+   * Internal storage for qualifier values using a ResultMap.
+   */
+  private readonly _qualifierValues: ResultMap<QualifierName, QualifierContextValue>;
+
+  /**
+   * Constructor for a {@link Runtime.SimpleContextQualifierProvider | SimpleContextQualifierProvider} object.
+   * @param params - {@link Runtime.ISimpleContextQualifierProviderCreateParams | Parameters} used to create the provider.
+   */
+  protected constructor(params: ISimpleContextQualifierProviderCreateParams) {
+    super();
+    this.qualifiers = params.qualifiers;
+    this._qualifierValues = new ResultMap<QualifierName, QualifierContextValue>();
+
+    if (params.qualifierValues) {
+      for (const [name, value] of Object.entries(params.qualifierValues)) {
+        const qualifierName = Validate.toQualifierName(name).orThrow();
+        this._qualifierValues.set(qualifierName, value);
+      }
+    }
+  }
+
+  /**
+   * Creates a new {@link Runtime.SimpleContextQualifierProvider | SimpleContextQualifierProvider} object.
+   * @param params - {@link Runtime.ISimpleContextQualifierProviderCreateParams | Parameters} used to create the provider.
+   * @returns `Success` with the new {@link Runtime.SimpleContextQualifierProvider | SimpleContextQualifierProvider} object if successful,
+   * or `Failure` with an error message if not.
+   * @public
+   */
+  public static create(
+    params: ISimpleContextQualifierProviderCreateParams
+  ): Result<SimpleContextQualifierProvider> {
+    return captureResult(() => new SimpleContextQualifierProvider(params));
+  }
+
+  /**
+   * Gets a qualifier value by its name, index, or qualifier object.
+   * @param nameOrIndexOrQualifier - The {@link QualifierName | qualifier name}, {@link QualifierIndex | index}, or {@link Qualifiers.Qualifier | qualifier object} to look up.
+   * @returns `Success` with the {@link QualifierContextValue | qualifier context value} if found,
+   * or `Failure` with an error message if not found or an error occurs.
+   */
+  public get(
+    nameOrIndexOrQualifier: QualifierName | QualifierIndex | Qualifier
+  ): Result<QualifierContextValue> {
+    const qualifierName = this._resolveQualifierName(nameOrIndexOrQualifier);
+    /* c8 ignore next 3 - functional code path tested but coverage intermittently missed */
+    if (qualifierName.isFailure()) {
+      return fail(qualifierName.message);
+    }
+    return this._qualifierValues.get(qualifierName.value);
+  }
+
+  /**
+   * Gets a validated qualifier context value by its name, index, or qualifier object.
+   * TODO: Implement validation logic using qualifier collectors.
+   * @param nameOrIndexOrQualifier - The {@link QualifierName | qualifier name}, {@link QualifierIndex | index}, or {@link Qualifiers.Qualifier | qualifier object} to look up.
+   * @returns `Success` with the validated {@link QualifierContextValue | qualifier context value} if found,
+   * or `Failure` with an error message if not found, invalid, or an error occurs.
+   */
+  public getValidated(
+    nameOrIndexOrQualifier: QualifierName | QualifierIndex | Qualifier
+  ): Result<QualifierContextValue> {
+    const qualifierName = this._resolveQualifierName(nameOrIndexOrQualifier);
+    if (qualifierName.isFailure()) {
+      return fail(qualifierName.message);
+    }
+    // TODO: Implement validation logic
+    return fail(`getValidated not yet implemented for qualifier "${qualifierName.value}"`);
+  }
+
+  /**
+   * Checks if a qualifier value exists with the given name.
+   * @param name - The {@link QualifierName | qualifier name} to check.
+   * @returns `Success` with `true` if the qualifier value exists, `false` if it doesn't,
+   * or `Failure` with an error message if an error occurs during the check.
+   */
+  public has(name: QualifierName): Result<boolean> {
+    return succeed(this._qualifierValues.has(name));
+  }
+
+  /**
+   * Gets all available qualifier names in this context.
+   * @returns `Success` with an array of all {@link QualifierName | qualifier names},
+   * or `Failure` with an error message if an error occurs.
+   */
+  public getNames(): Result<ReadonlyArray<QualifierName>> {
+    return succeed(Array.from(this._qualifierValues.keys()));
+  }
+
+  /**
+   * Sets a qualifier value in this provider.
+   * @param name - The {@link QualifierName | qualifier name} to set.
+   * @param value - The {@link QualifierContextValue | qualifier context value} to set.
+   * @returns `Success` with the set {@link QualifierContextValue | qualifier context value} if successful,
+   * or `Failure` with an error message if not.
+   * @public
+   */
+  public set(name: QualifierName, value: QualifierContextValue): Result<QualifierContextValue> {
+    this._qualifierValues.set(name, value);
+    return succeed(value);
+  }
+
+  /**
+   * Removes a qualifier value from this provider.
+   * @param name - The {@link QualifierName | qualifier name} to remove.
+   * @returns `Success` with the removed {@link QualifierContextValue | qualifier context value} if successful,
+   * or `Failure` with an error message if not found or an error occurs.
+   * @public
+   */
+  public remove(name: QualifierName): Result<QualifierContextValue> {
+    return this._qualifierValues.get(name).onSuccess((value) => {
+      this._qualifierValues.delete(name);
+      return succeedWithDetail(value, 'success');
+    });
+  }
+
+  /**
+   * Gets the number of qualifier values in this provider.
+   * @returns The count of qualifier values.
+   * @public
+   */
+  public get size(): number {
+    return this._qualifierValues.size;
+  }
+
+  /**
+   * Clears all qualifier values from this provider.
+   * @public
+   */
+  public clear(): void {
+    this._qualifierValues.clear();
+  }
+
+  /**
+   * Resolves a qualifier name from a name, index, or qualifier object.
+   * @param nameOrIndexOrQualifier - The input to resolve.
+   * @returns `Success` with the {@link QualifierName | qualifier name} if successful,
+   * or `Failure` with an error message if not found or invalid.
+   * @internal
+   */
+  private _resolveQualifierName(
+    nameOrIndexOrQualifier: QualifierName | QualifierIndex | Qualifier
+  ): Result<QualifierName> {
+    // If it's already a QualifierName (string type with brand)
+    if (typeof nameOrIndexOrQualifier === 'string') {
+      /* c8 ignore next 1 - functional code path tested but coverage intermittently missed */
+      return succeed(nameOrIndexOrQualifier as QualifierName);
+    }
+
+    // If it's a Qualifier object
+    if (
+      typeof nameOrIndexOrQualifier === 'object' &&
+      nameOrIndexOrQualifier !== null &&
+      'name' in nameOrIndexOrQualifier
+    ) {
+      return succeed(nameOrIndexOrQualifier.name);
+    }
+
+    // If it's a QualifierIndex (number type with brand)
+    /* c8 ignore next 8 - functional code path tested but coverage intermittently missed */
+    if (typeof nameOrIndexOrQualifier === 'number') {
+      const qualifier = this.qualifiers.getAt(nameOrIndexOrQualifier as QualifierIndex);
+      if (qualifier.isSuccess()) {
+        return succeed(qualifier.value.name);
+      }
+      return fail(`Qualifier not found at index ${nameOrIndexOrQualifier}`);
+    }
+
+    return fail(`Invalid qualifier parameter: ${nameOrIndexOrQualifier}`);
+  }
+}

package/src/packlets/runtime/context/validatingSimpleContextQualifierProvider.ts

@@ -0,0 +1,96 @@
+/*
+ * 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 { Result, captureResult } from '@fgv/ts-utils';
+import { QualifierContextValue } from '../../common';
+import { IReadOnlyQualifierCollector } from '../../qualifiers';
+import { SimpleContextQualifierProvider } from './simpleContextQualifierProvider';
+import {
+  ContextQualifierProviderValidator,
+  IReadOnlyContextQualifierProviderValidator
+} from './contextQualifierProviderValidator';
+
+/**
+ * Parameters for creating a {@link Runtime.ValidatingSimpleContextQualifierProvider | ValidatingSimpleContextQualifierProvider}.
+ * @public
+ */
+export interface IValidatingSimpleContextQualifierProviderCreateParams {
+  /**
+   * The {@link Qualifiers.IReadOnlyQualifierCollector | readonly qualifier collector} that defines and validates qualifiers.
+   */
+  qualifiers: IReadOnlyQualifierCollector;
+
+  /**
+   * Optional record of initial qualifier name-value pairs to populate the provider.
+   * Accepts string keys and values which will be converted to strongly-typed values.
+   */
+  qualifierValues?: Record<string, string>;
+}
+
+/**
+ * A {@link Runtime.SimpleContextQualifierProvider | SimpleContextQualifierProvider} with a
+ * {@link Runtime.Context.ContextQualifierProviderValidator | validator} property that enables
+ * validated use of the underlying provider with string keys and values.
+ * This eliminates the need for type casting in consumer code.
+ * @public
+ */
+export class ValidatingSimpleContextQualifierProvider extends SimpleContextQualifierProvider {
+  /**
+   * A {@link Runtime.Context.ContextQualifierProviderValidator | ContextQualifierProviderValidator} which validates
+   * string inputs before passing them to this provider.
+   */
+  public readonly validating: IReadOnlyContextQualifierProviderValidator;
+
+  /**
+   * Constructor for a {@link Runtime.ValidatingSimpleContextQualifierProvider | ValidatingSimpleContextQualifierProvider} object.
+   * @param params - {@link Runtime.IValidatingSimpleContextQualifierProviderCreateParams | Parameters} used to create the provider.
+   */
+  protected constructor(params: IValidatingSimpleContextQualifierProviderCreateParams) {
+    // Convert string values to QualifierContextValue for the base class
+    /* c8 ignore next 5 - functional code path tested but coverage intermittently missed */
+    const convertedValues: Record<string, QualifierContextValue> | undefined = params.qualifierValues
+      ? Object.fromEntries(
+          Object.entries(params.qualifierValues).map(([key, value]) => [key, value as QualifierContextValue])
+        )
+      : undefined;
+
+    super({
+      qualifiers: params.qualifiers,
+      qualifierValues: convertedValues
+    });
+
+    this.validating = new ContextQualifierProviderValidator({ provider: this });
+  }
+
+  /**
+   * Creates a new {@link Runtime.ValidatingSimpleContextQualifierProvider | ValidatingSimpleContextQualifierProvider} object.
+   * @param params - {@link Runtime.IValidatingSimpleContextQualifierProviderCreateParams | Parameters} used to create the provider.
+   * @returns `Success` with the new {@link Runtime.ValidatingSimpleContextQualifierProvider | ValidatingSimpleContextQualifierProvider} object if successful,
+   * or `Failure` with an error message if not.
+   * @public
+   */
+  public static create(
+    params: IValidatingSimpleContextQualifierProviderCreateParams
+  ): Result<ValidatingSimpleContextQualifierProvider> {
+    return captureResult(() => new ValidatingSimpleContextQualifierProvider(params));
+  }
+}

package/src/packlets/runtime/iResourceManager.ts

@@ -0,0 +1,130 @@
+/*
+ * 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 { Result, Collections } from '@fgv/ts-utils';
+import { JsonObject } from '@fgv/ts-json-base';
+import { ReadOnlyConditionCollector, ReadOnlyConditionSetCollector } from '../conditions';
+import { ReadOnlyAbstractDecisionCollector, ConcreteDecision } from '../decisions';
+import { ResourceId, ResourceValueMergeMethod } from '../common';
+import { IResourceType } from '../resource-types';
+import { IContextDecl, IValidatedContextDecl } from '../context';
+import { IReadOnlyResourceTreeRoot } from './resource-tree';
+
+/**
+ * Runtime representation of a resource candidate with the minimal data needed for resolution.
+ * @public
+ */
+export interface IResourceCandidate {
+  /** The JSON value for this candidate */
+  readonly json: JsonObject;
+
+  /**
+   * Indicates if this candidate is a partial resource.
+   */
+  readonly isPartial: boolean;
+
+  /**
+   * Specifies the resource type of this candidate.
+   */
+  readonly mergeMethod: ResourceValueMergeMethod;
+}
+
+/**
+ * Interface for a resource that can be used in the runtime layer.
+ * This provides the minimal properties needed from a resource without requiring
+ * the full Resources layer dependencies.
+ * @public
+ */
+export interface IResource {
+  /** The resource identifier */
+  readonly id: string;
+  /** The resource name */
+  readonly name: string;
+  /** The resource type */
+  readonly resourceType: IResourceType;
+  /** The decision used to select candidates */
+  readonly decision: ConcreteDecision;
+  /** The available candidates for this resource */
+  readonly candidates: ReadonlyArray<IResourceCandidate>;
+}
+
+/**
+ * Interface defining the read-only properties that the runtime resource resolver needs
+ * from a resource manager. This abstraction allows the runtime to work with different
+ * implementations without requiring the full ResourceManagerBuilder build mechanics.
+ * @public
+ */
+export interface IResourceManager<TR extends IResource = IResource> {
+  /**
+   * A {@link Conditions.ReadOnlyConditionCollector | ReadOnlyConditionCollector} which
+   * contains the {@link Conditions.Condition | conditions} used by resource candidates.
+   */
+  readonly conditions: ReadOnlyConditionCollector;
+
+  /**
+   * A {@link Conditions.ReadOnlyConditionSetCollector | ReadOnlyConditionSetCollector} which
+   * contains the {@link Conditions.ConditionSet | condition sets} used by resource candidates.
+   */
+  readonly conditionSets: ReadOnlyConditionSetCollector;
+
+  /**
+   * A {@link Decisions.ReadOnlyAbstractDecisionCollector | ReadOnlyAbstractDecisionCollector} which
+   * contains the {@link Decisions.Decision | abstract decisions} used by resource candidates.
+   */
+  readonly decisions: ReadOnlyAbstractDecisionCollector;
+
+  /**
+   * Gets a built resource by ID for runtime resolution.
+   * @param id - The resource identifier
+   * @returns Success with the runtime resource if found, Failure otherwise
+   */
+  getBuiltResource(id: string): Result<TR>;
+
+  /**
+   * Gets a resource tree built from the resources in this resource manager.
+   * @returns Result containing the resource tree root, or failure if tree construction fails
+   */
+  getBuiltResourceTree(): Result<IReadOnlyResourceTreeRoot<TR>>;
+
+  /**
+   * A read-only result map of all built resources, keyed by resource ID.
+   * Resources are built on-demand when accessed and returns Results for error handling.
+   */
+  readonly builtResources: Collections.IReadOnlyValidatingResultMap<ResourceId, TR>;
+
+  /**
+   * The number of resources in this resource manager.
+   */
+  readonly numResources: number;
+
+  /**
+   * The number of candidates in this resource manager.
+   */
+  readonly numCandidates: number;
+
+  /**
+   * Validates a context declaration against the qualifiers managed by this resource manager.
+   * @param context - The context declaration to validate
+   * @returns Success with the validated context if successful, Failure otherwise
+   */
+  validateContext(context: IContextDecl): Result<IValidatedContextDecl>;
+}

package/src/packlets/runtime/index.ts

@@ -0,0 +1,35 @@
+/*
+ * 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.
+ */
+
+export * from './compiledResourceCollection';
+export * from './iResourceManager';
+export * from './context/simpleContextQualifierProvider';
+export * from './context/validatingSimpleContextQualifierProvider';
+export * from './resourceResolver';
+export * from './conditionSetResolutionResult';
+export * from './cacheListener';
+export * from './cacheMetrics';
+
+import * as Context from './context';
+import * as ResourceTree from './resource-tree';
+
+export { Context, ResourceTree };

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

@@ -0,0 +1,126 @@
+/*
+ * 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 { IReadOnlyResultMap, Result } from '@fgv/ts-utils';
+import { ResourceId, ResourceName } from '../../common';
+
+/**
+ * Interface for leaf nodes in a resource tree.
+ * Leaf nodes contain resource values and cannot have child nodes.
+ * In a valid resource tree, if a path has child resources (e.g., 'app.messages.welcome'),
+ * then that path cannot itself be a resource (i.e., 'app' cannot be both a resource and have children).
+ * @public
+ */
+export interface IReadOnlyResourceTreeLeaf<T> {
+  readonly id: ResourceId;
+  readonly name: ResourceName;
+  readonly resource: T;
+  readonly isLeaf: true;
+  readonly isBranch: false;
+  readonly isRoot: false;
+}
+
+/**
+ * Interface for branch nodes in a resource tree that contain child nodes.
+ * Branch nodes organize the tree structure and cannot have resource values.
+ * If a path has child resources, it must be a branch and cannot itself be a resource.
+ * @public
+ */
+export interface IReadOnlyResourceTreeBranch<T> {
+  readonly id: ResourceId;
+  readonly name: ResourceName;
+  readonly children: IReadOnlyValidatingResourceTreeChildren<T>;
+  readonly isLeaf: false;
+  readonly isBranch: true;
+  readonly isRoot: false;
+}
+
+/**
+ * Interface for the root node of a resource tree.
+ * @public
+ */
+export interface IReadOnlyResourceTreeRoot<T> {
+  readonly children: IReadOnlyValidatingResourceTreeChildren<T>;
+  readonly isRoot: true;
+  readonly isLeaf: false;
+  readonly isBranch: false;
+}
+
+/**
+ * Union type representing any node in the resource tree, which can be a leaf or a branch.
+ * This allows for flexible handling of different node types in the tree structure.
+ * @public
+ */
+export type IReadOnlyResourceTreeNode<T> = IReadOnlyResourceTreeLeaf<T> | IReadOnlyResourceTreeBranch<T>;
+
+/**
+ * Interface for a read-only result-based resource tree with navigation methods.
+ * @public
+ */
+export interface IReadOnlyResourceTreeChildren<
+  T,
+  TID extends string = ResourceId,
+  TNAME extends string = ResourceName
+> extends IReadOnlyResultMap<ResourceName, IReadOnlyResourceTreeNode<T>> {
+  /**
+   * Gets a tree node by its full ResourceId path.
+   * @param id - The ResourceId path to look up
+   * @returns Result containing the node if found, or failure if not found
+   */
+  getById(id: TID): Result<IReadOnlyResourceTreeNode<T>>;
+
+  /**
+   * Gets a resource node by its direct name (single component).
+   * @param name - The ResourceName to look up
+   * @returns Result containing the node if it's a resource, or failure if not found or not a resource
+   */
+  getResource(name: TNAME): Result<IReadOnlyResourceTreeNode<T>>;
+
+  /**
+   * Gets a branch node by its direct name (single component).
+   * @param name - The ResourceName to look up
+   * @returns Result containing the node if it's a branch, or failure if not found or not a branch
+   */
+  getBranch(name: TNAME): Result<IReadOnlyResourceTreeNode<T>>;
+
+  /**
+   * Gets a resource leaf node by its full ResourceId path.
+   * @param id - The ResourceId path to look up
+   * @returns Result containing the leaf if found and is a resource, or failure otherwise
+   */
+  getResourceById(id: TID): Result<IReadOnlyResourceTreeLeaf<T>>;
+
+  /**
+   * Gets a branch node by its full ResourceId path.
+   * @param id - The ResourceId path to look up
+   * @returns Result containing the branch if found and has children, or failure otherwise
+   */
+  getBranchById(id: TID): Result<IReadOnlyResourceTreeBranch<T>>;
+}
+
+/**
+ * A read-only interface for accessing resource tree children using weakly-typed string keys.
+ * @public
+ */
+export interface IReadOnlyValidatingResourceTreeChildren<T> extends IReadOnlyResourceTreeChildren<T> {
+  readonly validating: IReadOnlyResourceTreeChildren<T, string, string>;
+}

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

@@ -0,0 +1,26 @@
+/*
+ * 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.
+ */
+
+export * from './common';
+export * from './resourceTreeChildren';
+export * from './resourceTreeChildrenValidator';
+export * from './readOnlyResourceTree';