@fgv/ts-res 5.0.1-8 → 5.0.1

package/dist/packlets/runtime/resourceResolver.js

@@ -0,0 +1,481 @@
+/*
+ * 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 { captureResult, fail, succeed } from '@fgv/ts-utils';
+import { isJsonObject } from '@fgv/ts-json-base';
+import { JsonEditor } from '@fgv/ts-json';
+import { NoMatch } from '../common';
+import { ValidatingSimpleContextQualifierProvider } from './context';
+import { ConditionSetResolutionResult } from './conditionSetResolutionResult';
+/**
+ * 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 class ResourceResolver {
+    /**
+     * The readonly qualifier collector that provides qualifier implementations.
+     */
+    get qualifiers() {
+        return this.contextQualifierProvider.qualifiers;
+    }
+    /**
+     * The resource IDs that this resolver can resolve.
+     */
+    get resourceIds() {
+        return this.resourceManager.resourceIds;
+    }
+    /**
+     * 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() {
+        return this._conditionCache;
+    }
+    /**
+     * 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() {
+        return this._conditionSetCache;
+    }
+    /**
+     * 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() {
+        return this._decisionCache;
+    }
+    /**
+     * Constructor for a {@link Runtime.ResourceResolver | ResourceResolver} object.
+     * @param params - {@link Runtime.IResourceResolverCreateParams | Parameters} used to create the resolver.
+     */
+    constructor(params) {
+        var _a, _b;
+        this.resourceManager = params.resourceManager;
+        this.qualifierTypes = params.qualifierTypes;
+        this.contextQualifierProvider = params.contextQualifierProvider;
+        this.options = {
+            suppressNullAsDelete: (_b = (_a = params.options) === null || _a === void 0 ? void 0 : _a.suppressNullAsDelete) !== null && _b !== void 0 ? _b : false
+        };
+        // Initialize condition cache array with size matching the condition collector
+        const conditionCollectorSize = this.resourceManager.conditions.size;
+        this._conditionCache = new Array(conditionCollectorSize);
+        // Initialize condition set cache array with size matching the condition set collector
+        const conditionSetCollectorSize = this.resourceManager.conditionSets.size;
+        this._conditionSetCache = new Array(conditionSetCollectorSize);
+        // Initialize decision cache array with size matching the decision collector
+        const decisionCollectorSize = this.resourceManager.decisions.size;
+        this._decisionCache = new Array(decisionCollectorSize);
+        this._listener = params.listener;
+    }
+    /**
+     * 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) {
+        return captureResult(() => new ResourceResolver(params));
+    }
+    /**
+     * 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) {
+        var _a, _b, _c;
+        // Get the condition's index for cache lookup
+        const conditionIndex = condition.index;
+        if (conditionIndex === undefined) {
+            return fail(`Condition "${condition.key}" does not have a valid index`);
+        }
+        // Check cache first for O(1) lookup
+        const cachedResult = this._conditionCache[conditionIndex];
+        if (cachedResult !== undefined) {
+            (_a = this._listener) === null || _a === void 0 ? void 0 : _a.onCacheHit('condition', conditionIndex);
+            return succeed(cachedResult);
+        }
+        // Resolve the condition by getting qualifier value and evaluating with qualifier type
+        const score = this.contextQualifierProvider
+            .get(condition.qualifier)
+            .onSuccess((qualifierValue) => {
+            // Evaluate the condition using the qualifier type's matching logic
+            return succeed(condition.qualifier.type.matches(condition.value, qualifierValue, condition.operator));
+        })
+            .onFailure((err) => {
+            var _a;
+            (_a = this._listener) === null || _a === void 0 ? void 0 : _a.onContextError(condition.qualifier.name, err);
+            return fail(err);
+        })
+            .orDefault(NoMatch);
+        const priority = condition.priority;
+        const scoreAsDefault = (_b = condition.scoreAsDefault) !== null && _b !== void 0 ? _b : NoMatch;
+        const matchResult = score > NoMatch
+            ? { score, priority, matchType: 'match' }
+            : scoreAsDefault > NoMatch
+                ? { score: scoreAsDefault, priority, matchType: 'matchAsDefault' }
+                : { score: NoMatch, priority, matchType: 'noMatch' };
+        // Cache the resolved value for future O(1) lookup
+        this._conditionCache[conditionIndex] = matchResult;
+        (_c = this._listener) === null || _c === void 0 ? void 0 : _c.onCacheMiss('condition', conditionIndex);
+        return succeed(matchResult);
+    }
+    /**
+     * 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) {
+        var _a, _b;
+        // Get the condition set's index for cache lookup
+        const conditionSetIndex = conditionSet.index;
+        if (conditionSetIndex === undefined) {
+            return fail(`ConditionSet "${conditionSet.key}" does not have a valid index`);
+        }
+        // Check cache first for O(1) lookup
+        const cachedResult = this._conditionSetCache[conditionSetIndex];
+        if (cachedResult !== undefined) {
+            (_a = this._listener) === null || _a === void 0 ? void 0 : _a.onCacheHit('conditionSet', conditionSetIndex);
+            return succeed(cachedResult);
+        }
+        // Resolve all conditions in the condition set
+        const conditions = [];
+        let matchType = 'match';
+        for (const condition of conditionSet.conditions) {
+            const { value: conditionResult, message: conditionMessage } = this.resolveCondition(condition);
+            /* c8 ignore next 4 - defensive coding: extreme internal error scenario not reachable in normal operation */
+            if (conditionMessage !== undefined) {
+                (_b = this._listener) === null || _b === void 0 ? void 0 : _b.onCacheError('conditionSet', conditionSetIndex);
+                return fail(`Failed to resolve condition "${condition.key}": ${conditionMessage}`);
+            }
+            conditions.push(conditionResult);
+            if (conditionResult.matchType === 'noMatch') {
+                // Cache the failure result
+                return ConditionSetResolutionResult.create('noMatch', conditions)
+                    .onSuccess((result) => {
+                    var _a;
+                    this._conditionSetCache[conditionSetIndex] = result;
+                    (_a = this._listener) === null || _a === void 0 ? void 0 : _a.onCacheMiss('conditionSet', conditionSetIndex);
+                    return succeed(result);
+                })
+                    .onFailure((err) => {
+                    var _a;
+                    /* c8 ignore next 4 - defensive coding: extreme internal error scenario not reachable in normal operation */
+                    this._conditionSetCache[conditionSetIndex] = undefined;
+                    (_a = this._listener) === null || _a === void 0 ? void 0 : _a.onCacheError('conditionSet', conditionSetIndex);
+                    return fail(`${conditionSetIndex}: error creating condition set resolution result: ${err}`);
+                });
+            }
+            /* c8 ignore next 3 - edge case: matchAsDefault fallback logic rarely triggered */
+            if (conditionResult.matchType === 'matchAsDefault') {
+                matchType = 'matchAsDefault';
+            }
+        }
+        // Cache the successful result
+        return ConditionSetResolutionResult.create(matchType, conditions)
+            .onSuccess((result) => {
+            var _a;
+            this._conditionSetCache[conditionSetIndex] = result;
+            (_a = this._listener) === null || _a === void 0 ? void 0 : _a.onCacheMiss('conditionSet', conditionSetIndex);
+            return succeed(result);
+        })
+            .onFailure((err) => {
+            var _a;
+            /* c8 ignore next 4 - defensive coding: extreme internal error scenario not reachable in normal operation */
+            this._conditionSetCache[conditionSetIndex] = undefined;
+            (_a = this._listener) === null || _a === void 0 ? void 0 : _a.onCacheError('conditionSet', conditionSetIndex);
+            return fail(`${conditionSetIndex}: error creating condition set resolution result: ${err}`);
+        });
+    }
+    /**
+     * 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) {
+        var _a, _b, _c;
+        // Get the decision's index for cache lookup
+        const decisionIndex = decision.index;
+        if (decisionIndex === undefined) {
+            return fail(`Decision "${decision.key}" does not have a valid index`);
+        }
+        // Check cache first for O(1) lookup
+        const cachedResult = this._decisionCache[decisionIndex];
+        if (cachedResult !== undefined) {
+            (_a = this._listener) === null || _a === void 0 ? void 0 : _a.onCacheHit('decision', decisionIndex);
+            return succeed(cachedResult);
+        }
+        // Resolve all condition sets in the decision
+        const matchingInstanceResults = [];
+        const matchingDefaultInstanceResults = [];
+        for (let instanceIndex = 0; instanceIndex < decision.candidates.length; instanceIndex++) {
+            const candidate = decision.candidates[instanceIndex];
+            const conditionSetResult = this.resolveConditionSet(candidate.conditionSet);
+            /* c8 ignore next 4 - defensive in depth */
+            if (conditionSetResult.isFailure()) {
+                (_b = this._listener) === null || _b === void 0 ? void 0 : _b.onCacheError('decision', decisionIndex);
+                return fail(`${decision.key}: Failed to resolve condition set": ${conditionSetResult.message}`);
+            }
+            const resolution = conditionSetResult.value;
+            // Only include condition sets that match
+            if (resolution.matchType === 'match') {
+                matchingInstanceResults.push({
+                    index: instanceIndex,
+                    result: resolution
+                });
+            }
+            else if (resolution.matchType === 'matchAsDefault') {
+                matchingDefaultInstanceResults.push({
+                    index: instanceIndex,
+                    result: resolution
+                });
+            }
+            // If condition set doesn't match, we simply skip it and continue (don't fail the decision)
+        }
+        // Sort by condition set resolution priority using the proper comparison logic
+        matchingInstanceResults.sort((a, b) => ConditionSetResolutionResult.compare(a.result, b.result));
+        matchingDefaultInstanceResults.sort((a, b) => ConditionSetResolutionResult.compare(a.result, b.result));
+        // Extract just the instance indices in priority order
+        const instanceIndices = matchingInstanceResults.map((item) => item.index);
+        const defaultInstanceIndices = matchingDefaultInstanceResults.map((item) => item.index);
+        // Cache the successful result
+        const successResult = {
+            success: true,
+            instanceIndices,
+            defaultInstanceIndices
+        };
+        this._decisionCache[decisionIndex] = successResult;
+        (_c = this._listener) === null || _c === void 0 ? void 0 : _c.onCacheMiss('decision', decisionIndex);
+        return succeed(successResult);
+    }
+    resolveResource(idOrResource) {
+        /* c8 ignore next 4 - defensive coding: string resource resolution should use direct resource calls */
+        if (typeof idOrResource === 'string') {
+            return this.resourceManager
+                .getBuiltResource(idOrResource)
+                .onSuccess((resource) => this.resolveResource(resource));
+        }
+        const resource = idOrResource;
+        // Get the abstract decision from the resource's concrete decision
+        const abstractDecision = resource.decision.baseDecision;
+        // Resolve the decision to get candidate indices in priority order
+        const decisionResult = this.resolveDecision(abstractDecision);
+        /* c8 ignore next 3 - defense in depth almost impossible to hit */
+        if (decisionResult.isFailure()) {
+            return fail(`Failed to resolve decision for resource "${resource.id}": ${decisionResult.message}`);
+        }
+        const resolution = decisionResult.value;
+        // Check if any candidates matched (regular or default)
+        if (!resolution.success ||
+            (resolution.instanceIndices.length === 0 && resolution.defaultInstanceIndices.length === 0)) {
+            return fail(`No matching candidates found for resource "${resource.id}"`);
+        }
+        // Prefer regular matches over default matches
+        const candidateIndex = resolution.instanceIndices.length > 0
+            ? resolution.instanceIndices[0] // Best regular match
+            : resolution.defaultInstanceIndices[0]; // Best default match
+        if (candidateIndex >= resource.candidates.length) {
+            return fail(`Invalid candidate index ${candidateIndex} for resource "${resource.id}"`);
+        }
+        const bestCandidate = resource.candidates[candidateIndex];
+        return succeed(bestCandidate);
+    }
+    resolveAllResourceCandidates(idOrResource) {
+        if (typeof idOrResource === 'string') {
+            return this.resourceManager
+                .getBuiltResource(idOrResource)
+                .onSuccess((resource) => this.resolveAllResourceCandidates(resource));
+        }
+        const resource = idOrResource;
+        // Get the abstract decision from the resource's concrete decision
+        const abstractDecision = resource.decision.baseDecision;
+        // Resolve the decision to get candidate indices in priority order
+        const decisionResult = this.resolveDecision(abstractDecision);
+        /* c8 ignore next 3 - defense in depth almost impossible to hit */
+        if (decisionResult.isFailure()) {
+            return fail(`Failed to resolve decision for resource "${resource.id}": ${decisionResult.message}`);
+        }
+        const resolution = decisionResult.value;
+        // Check if any candidates matched (regular or default)
+        if (!resolution.success ||
+            (resolution.instanceIndices.length === 0 && resolution.defaultInstanceIndices.length === 0)) {
+            return fail(`No matching candidates found for resource "${resource.id}"`);
+        }
+        // Get all matching candidates: regular matches first, then default matches
+        const candidates = [];
+        // Add all regular matches first (already sorted by priority)
+        for (const candidateIndex of resolution.instanceIndices) {
+            if (candidateIndex >= resource.candidates.length) {
+                return fail(`Invalid candidate index ${candidateIndex} for resource "${resource.id}"`);
+            }
+            const candidate = resource.candidates[candidateIndex];
+            candidates.push(candidate);
+        }
+        // Add all default matches after regular matches (already sorted by priority)
+        for (const candidateIndex of resolution.defaultInstanceIndices) {
+            /* c8 ignore next 3 - defense in depth should not happen */
+            if (candidateIndex >= resource.candidates.length) {
+                return fail(`Invalid candidate index ${candidateIndex} for resource "${resource.id}"`);
+            }
+            const candidate = resource.candidates[candidateIndex];
+            candidates.push(candidate);
+        }
+        return succeed(candidates);
+    }
+    resolveComposedResourceValue(idOrResource) {
+        /* c8 ignore next 4 - defensive coding: string resource resolution should use direct resource calls */
+        if (typeof idOrResource === 'string') {
+            return this.resourceManager
+                .getBuiltResource(idOrResource)
+                .onSuccess((resource) => this.resolveComposedResourceValue(resource));
+        }
+        const resource = idOrResource;
+        return this.resolveAllResourceCandidates(resource).onSuccess((candidates) => {
+            /* c8 ignore next 3 - defense in depth should never occur */
+            if (candidates.length === 0) {
+                return fail(`${resource.id}: No matching candidates found.`);
+            }
+            // Find the first full candidate and collect all partial candidates above it
+            let fullCandidateIndex = -1;
+            const partialCandidates = [];
+            for (let i = 0; i < candidates.length; i++) {
+                const candidate = candidates[i];
+                if (!candidate.isPartial) {
+                    // Found the first full candidate
+                    fullCandidateIndex = i;
+                    break;
+                }
+                else {
+                    // Collect partial candidates (these are in ascending priority order)
+                    partialCandidates.unshift(candidate);
+                }
+            }
+            // If no full candidate found, use the last candidate as the base
+            const baseCandidateIndex = fullCandidateIndex >= 0 ? fullCandidateIndex : candidates.length - 1;
+            const baseCandidate = candidates[baseCandidateIndex];
+            // If there are no partial candidates to merge, but null-as-delete is enabled,
+            // still process through JsonEditor to handle null properties in the base candidate
+            if (partialCandidates.length === 0) {
+                if (this.options.suppressNullAsDelete || !isJsonObject(baseCandidate.json)) {
+                    return succeed(baseCandidate.json);
+                }
+                // Process single candidate through JsonEditor to apply null-as-delete
+                const editor = JsonEditor.create({
+                    merge: {
+                        arrayMergeBehavior: 'replace',
+                        nullAsDelete: true
+                    }
+                }).orThrow(); // Should never fail with valid options
+                return editor
+                    .mergeObjectsInPlace({}, [baseCandidate.json])
+                    .withErrorFormat((err) => `${resource.id}: Composition failed: ${err}`);
+            }
+            const allCandidates = [
+                baseCandidate.json,
+                ...partialCandidates.map((candidate) => candidate.json)
+            ].filter((v) => isJsonObject(v));
+            /* c8 ignore next 3 - defensive check: non-object values in resource candidates should be prevented at validation time */
+            if (allCandidates.length !== partialCandidates.length + 1) {
+                return fail(`${resource.id}: Unable to compose non-object candidate values.`);
+            }
+            // Create JsonEditor with array replacement behavior and null-as-delete for resource composition
+            const editor = JsonEditor.create({
+                merge: {
+                    arrayMergeBehavior: 'replace',
+                    nullAsDelete: !this.options.suppressNullAsDelete
+                }
+            }).orThrow(); // Should never fail with valid options
+            return editor
+                .mergeObjectsInPlace({}, allCandidates)
+                .withErrorFormat((err) => `${resource.id}: Composition failed: ${err}`);
+        });
+    }
+    /**
+     * {@inheritDoc IResourceResolver.withContext}
+     */
+    withContext(context) {
+        const { resourceManager, qualifierTypes, options } = this;
+        return ValidatingSimpleContextQualifierProvider.create({
+            qualifiers: this.qualifiers,
+            qualifierValues: context
+        }).onSuccess((contextQualifierProvider) => {
+            return ResourceResolver.create({
+                resourceManager,
+                qualifierTypes,
+                options,
+                contextQualifierProvider
+            });
+        });
+    }
+    /**
+     * 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() {
+        var _a, _b, _c;
+        this._conditionCache.fill(undefined);
+        this._conditionSetCache.fill(undefined);
+        this._decisionCache.fill(undefined);
+        (_a = this._listener) === null || _a === void 0 ? void 0 : _a.onCacheClear('condition');
+        (_b = this._listener) === null || _b === void 0 ? void 0 : _b.onCacheClear('conditionSet');
+        (_c = this._listener) === null || _c === void 0 ? void 0 : _c.onCacheClear('decision');
+    }
+    /**
+     * Gets the current size of the condition cache array.
+     * @returns The size of the condition cache array.
+     * @public
+     */
+    get conditionCacheSize() {
+        return this._conditionCache.length;
+    }
+    /**
+     * Gets the current size of the condition set cache array.
+     * @returns The size of the condition set cache array.
+     * @public
+     */
+    get conditionSetCacheSize() {
+        return this._conditionSetCache.length;
+    }
+    /**
+     * Gets the current size of the decision cache array.
+     * @returns The size of the decision cache array.
+     * @public
+     */
+    get decisionCacheSize() {
+        return this._decisionCache.length;
+    }
+}
+//# sourceMappingURL=resourceResolver.js.map