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

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

@@ -0,0 +1,165 @@
+"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.ResourceTreeChildrenValidator = void 0;
+const common_1 = require("../../common");
+const ts_utils_1 = require("@fgv/ts-utils");
+/**
+ * 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
+ */
+class ResourceTreeChildrenValidator {
+    /**
+     * Creates a new validator wrapper for resource tree children.
+     * @param inner - The underlying resource tree children collection to wrap with validation
+     */
+    constructor(inner) {
+        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
+     */
+    getById(id) {
+        return common_1.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
+     */
+    getResource(name) {
+        return common_1.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
+     */
+    getBranch(name) {
+        return common_1.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
+     */
+    getResourceById(id) {
+        return common_1.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
+     */
+    getBranchById(id) {
+        return common_1.Validate.toResourceId(id).onSuccess((resourceId) => {
+            return this._inner.getBranchById(resourceId);
+        });
+    }
+    /**
+     * The number of direct child nodes in this collection.
+     */
+    get size() {
+        return this._inner.size;
+    }
+    /**
+     * Returns an iterator of [ResourceName, node] pairs for all child nodes.
+     * @returns Map iterator for all child nodes
+     */
+    entries() {
+        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
+     */
+    forEach(cb, arg) {
+        for (const [key, value] of this._inner.entries()) {
+            cb(value, key, this, arg);
+        }
+    }
+    /**
+     * 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) {
+        if (common_1.Validate.isValidResourceName(key)) {
+            return this._inner.get(key);
+        }
+        return (0, ts_utils_1.failWithDetail)(`${key}: invalid resource name.`, 'invalid-key');
+    }
+    /**
+     * 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) {
+        return this._inner.has(key);
+    }
+    /**
+     * Returns an iterator of ResourceName keys for all child nodes.
+     * @returns Map iterator for all child node keys
+     */
+    keys() {
+        return this._inner.keys();
+    }
+    /**
+     * Returns an iterator of child node values.
+     * @returns Map iterator for all child node values
+     */
+    values() {
+        return this._inner.values();
+    }
+    /**
+     * Returns an iterator for [ResourceName, node] pairs, enabling for...of iteration.
+     * @returns Iterable iterator for all child nodes
+     */
+    [Symbol.iterator]() {
+        return this._inner[Symbol.iterator]();
+    }
+}
+exports.ResourceTreeChildrenValidator = ResourceTreeChildrenValidator;
+//# sourceMappingURL=resourceTreeChildrenValidator.js.map

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

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

package/lib/packlets/runtime/resourceResolver.d.ts

@@ -0,0 +1,196 @@
+import { Result } from '@fgv/ts-utils';
+import { JsonValue } from '@fgv/ts-json-base';
+import { Condition, ConditionSet } from '../conditions';
+import { AbstractDecision } from '../decisions';
+import { ReadOnlyQualifierTypeCollector } from '../qualifier-types';
+import { IContextQualifierProvider } from './context';
+import { IResourceManager, IResource, IResourceCandidate } from './iResourceManager';
+import { ConditionSetResolutionResult, IConditionMatchResult } from './conditionSetResolutionResult';
+import { IResourceResolverCacheListener } from './cacheListener';
+/**
+ * Represents the cached result of resolving a decision.
+ * Contains either a failure indicator or a list of instance indices for matching condition sets,
+ * ordered by condition set priority.
+ * @public
+ */
+export type DecisionResolutionResult = {
+    success: false;
+} | {
+    success: true;
+    instanceIndices: ReadonlyArray<number>;
+    defaultInstanceIndices: ReadonlyArray<number>;
+};
+/**
+ * Parameters for creating a {@link Runtime.ResourceResolver | ResourceResolver}.
+ * @public
+ */
+export interface IResourceResolverCreateParams {
+    /**
+     * The {@link Runtime.IResourceManager | resource manager} that defines the resources available
+     * and provides access to qualifiers and conditions.
+     */
+    resourceManager: IResourceManager;
+    /**
+     * The {@link QualifierTypes.ReadOnlyQualifierTypeCollector | readonly qualifier type collector}
+     * that provides qualifier implementations for condition evaluation.
+     */
+    qualifierTypes: ReadOnlyQualifierTypeCollector;
+    /**
+     * The {@link Runtime.Context.IContextQualifierProvider | context qualifier provider} that resolves
+     * qualifier values for the current context.
+     */
+    contextQualifierProvider: IContextQualifierProvider;
+    /**
+     * An optional listener for {@link Runtime.ResourceResolver | ResourceResolver} cache activity.
+     */
+    listener?: IResourceResolverCacheListener;
+}
+/**
+ * High-performance runtime resource resolver with O(1) condition caching.
+ * Resolves resources for a given context by evaluating conditions against qualifier values
+ * and caching results for optimal performance.
+ * @public
+ */
+export declare class ResourceResolver {
+    /**
+     * The resource manager that defines available resources and provides condition access.
+     */
+    readonly resourceManager: IResourceManager;
+    /**
+     * The readonly qualifier type collector that provides qualifier implementations.
+     */
+    readonly qualifierTypes: ReadOnlyQualifierTypeCollector;
+    /**
+     * The context qualifier provider that resolves qualifier values.
+     */
+    readonly contextQualifierProvider: IContextQualifierProvider;
+    /**
+     * The cache array for resolved conditions, indexed by condition index for O(1) lookup.
+     * Each entry stores the resolved {@link Runtime.IConditionMatchResult | condition match result} for
+     * the corresponding condition.
+     */
+    get conditionCache(): ReadonlyArray<IConditionMatchResult | undefined>;
+    /**
+     * The cache array for resolved condition sets, indexed by condition set index for O(1) lookup.
+     * Each entry stores the resolved ConditionSetResolutionResult for the corresponding condition set.
+     */
+    get conditionSetCache(): ReadonlyArray<ConditionSetResolutionResult | undefined>;
+    /**
+     * The cache array for resolved decisions, indexed by decision index for O(1) lookup.
+     * Each entry stores the resolved DecisionResolutionResult for the corresponding decision.
+     */
+    get decisionCache(): ReadonlyArray<DecisionResolutionResult | undefined>;
+    /**
+     * Cache array for resolved conditions, indexed by condition index for O(1) lookup.
+     * Each entry stores the resolved QualifierMatchScore for the corresponding condition.
+     */
+    private readonly _conditionCache;
+    /**
+     * Cache array for resolved condition sets, indexed by condition set index for O(1) lookup.
+     * Each entry stores the resolved ConditionSetResolutionResult for the corresponding condition set.
+     */
+    private readonly _conditionSetCache;
+    /**
+     * Cache array for resolved decisions, indexed by decision index for O(1) lookup.
+     * Each entry stores the resolved DecisionResolutionResult for the corresponding decision.
+     */
+    private readonly _decisionCache;
+    /**
+     * The listener for {@link Runtime.ResourceResolver | ResourceResolver} cache activity.
+     */
+    private readonly _listener?;
+    /**
+     * Constructor for a {@link Runtime.ResourceResolver | ResourceResolver} object.
+     * @param params - {@link Runtime.IResourceResolverCreateParams | Parameters} used to create the resolver.
+     */
+    protected constructor(params: IResourceResolverCreateParams);
+    /**
+     * Creates a new {@link Runtime.ResourceResolver | ResourceResolver} object.
+     * @param params - {@link Runtime.IResourceResolverCreateParams | Parameters} used to create the resolver.
+     * @returns `Success` with the new {@link Runtime.ResourceResolver | ResourceResolver} object if successful,
+     * or `Failure` with an error message if not.
+     * @public
+     */
+    static create(params: IResourceResolverCreateParams): Result<ResourceResolver>;
+    /**
+     * Resolves a condition by evaluating it against the current context.
+     * Uses O(1) caching based on the condition's globally unique sequential index.
+     * @param condition - The {@link Conditions.Condition | condition} to resolve.
+     * @returns `Success` with the {@link QualifierMatchScore | match score} if successful,
+     * or `Failure` with an error message if the condition cannot be resolved.
+     * @public
+     */
+    resolveCondition(condition: Condition): Result<IConditionMatchResult>;
+    /**
+     * Resolves a condition set by evaluating all its constituent conditions against the current context.
+     * Uses O(1) caching based on the condition set's globally unique sequential index.
+     * @param conditionSet - The {@link Conditions.ConditionSet | condition set} to resolve.
+     * @returns `Success` with the {@link Runtime.ConditionSetResolutionResult | resolution result} if successful,
+     * or `Failure` with an error message if the condition set cannot be resolved.
+     * @public
+     */
+    resolveConditionSet(conditionSet: ConditionSet): Result<ConditionSetResolutionResult>;
+    /**
+     * Resolves a decision by evaluating all its constituent condition sets against the current context.
+     * Uses O(1) caching based on the decision's globally unique sequential index.
+     * @param decision - The {@link Decisions.AbstractDecision | abstract decision} to resolve.
+     * @returns `Success` with the {@link Runtime.DecisionResolutionResult | resolution result} if successful,
+     * or `Failure` with an error message if the decision cannot be resolved.
+     * @public
+     */
+    resolveDecision(decision: AbstractDecision): Result<DecisionResolutionResult>;
+    /**
+     * Resolves a resource by finding the best matching candidate.
+     * Uses the resource's associated decision to determine the best match based on the current context.
+     * @param resource - The {@link Resources.Resource | resource} to resolve.
+     * @returns `Success` with the best matching candidate if successful,
+     * or `Failure` with an error message if no candidates match or resolution fails.
+     * @public
+     */
+    resolveResource(resource: IResource): Result<IResourceCandidate>;
+    /**
+     * Resolves all matching resource candidates in priority order.
+     * Uses the resource's associated decision to determine all matching candidates based on the current context.
+     * @param resource - The {@link Resources.Resource | resource} to resolve.
+     * @returns `Success` with an array of all matching candidates in priority order if successful,
+     * or `Failure` with an error message if no candidates match or resolution fails.
+     * @public
+     */
+    resolveAllResourceCandidates(resource: IResource): Result<ReadonlyArray<IResourceCandidate>>;
+    /**
+     * Resolves a resource to a composed value by merging matching candidates according to their merge methods.
+     * Starting from the highest priority candidates, finds the first "full" candidate and merges all higher
+     * priority "partial" candidates into it in ascending order of priority.
+     * @param resource - The {@link Resources.Resource | resource} to resolve.
+     * @returns `Success` with the composed JsonValue if successful,
+     * or `Failure` with an error message if no candidates match or resolution fails.
+     * @public
+     */
+    resolveComposedResourceValue(resource: IResource): Result<JsonValue>;
+    /**
+     * Clears all caches (condition, condition set, and decision), forcing all cached items
+     * to be re-evaluated on next access. This should be called when the context changes and cached
+     * results are no longer valid.
+     * @public
+     */
+    clearConditionCache(): void;
+    /**
+     * Gets the current size of the condition cache array.
+     * @returns The size of the condition cache array.
+     * @public
+     */
+    get conditionCacheSize(): number;
+    /**
+     * Gets the current size of the condition set cache array.
+     * @returns The size of the condition set cache array.
+     * @public
+     */
+    get conditionSetCacheSize(): number;
+    /**
+     * Gets the current size of the decision cache array.
+     * @returns The size of the decision cache array.
+     * @public
+     */
+    get decisionCacheSize(): number;
+}
+//# sourceMappingURL=resourceResolver.d.ts.map

package/lib/packlets/runtime/resourceResolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resourceResolver.d.ts","sourceRoot":"","sources":["../../../src/packlets/runtime/resourceResolver.ts"],"names":[],"mappings":"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"}