@fgv/ts-res 5.0.1-9 → 5.0.1

package/dist/packlets/resources/resourceBuilder.js

@@ -0,0 +1,183 @@
+/*
+ * 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 { ResultMap, captureResult, fail, failWithDetail, succeed, succeedWithDetail } from '@fgv/ts-utils';
+import { Validate } from '../common';
+import { ResourceCandidate } from './resourceCandidate';
+import { Resource } from './resource';
+/**
+ * Represents a builder for a single logical {@link Resources.Resource | resource}.  Collects candidates
+ * with a common resource ID, validates them against each other and builds a {@link Resources.Resource | resource}
+ * object once all candidates are collected.
+ * @public
+ */
+export class ResourceBuilder {
+    /**
+     * Supplied or inferred {@link ResourceTypes.ResourceType | type} of the resource being built.
+     * If no type is supplied, the type will be inferred from the candidates - at least one candidate must
+     * define resource type and all candidates must be of the same type.
+     */
+    get resourceType() {
+        return this._resourceType;
+    }
+    /**
+     * Array of {@link Resources.ResourceCandidate | candidates} for the resource being built.
+     */
+    get candidates() {
+        return Array.from(this._candidates.values()).sort(ResourceCandidate.compare).reverse();
+    }
+    /**
+     * Constructor for a {@link Resources.ResourceBuilder | ResourceBuilder} object.
+     * @param params - Parameters to construct the new {@link Resources.ResourceBuilder | ResourceBuilder}.
+     */
+    constructor(params) {
+        this.id = Validate.toResourceId(params.id).orThrow();
+        this._resourceTypes = params.resourceTypes;
+        this._conditionSets = params.conditionSets;
+        this._decisions = params.decisions;
+        this._candidateValues = params.candidateValues;
+        this._candidates = new ResultMap();
+        if (params.typeName) {
+            this._resourceType = this._resourceTypes.validating.get(params.typeName).orThrow();
+        }
+    }
+    /**
+     * Creates a new {@link Resources.ResourceBuilder | ResourceBuilder} object.
+     * @param params - Parameters to create a new {@link Resources.ResourceBuilder | ResourceBuilder}.
+     * @returns `Success` with the new {@link Resources.ResourceBuilder | ResourceBuilder} object if successful,
+     * or `Failure` with an error message if not.
+     * @public
+     */
+    static create(params) {
+        return captureResult(() => new ResourceBuilder(params));
+    }
+    /**
+     * Gets the {@link Resources.ResourceCandidate | candidates} that match a given {@link Context.IValidatedContextDecl | context}.
+     * @param context - The {@link Context.IValidatedContextDecl | context} to get candidates for.
+     * @param options - Optional {@link Context.IContextMatchOptions | context match options} to use when matching candidates.
+     * @returns An array of {@link Resources.ResourceCandidate | candidates} that match the given context.
+     */
+    getCandidatesForContext(context, options) {
+        return Array.from(this._candidates.values()).filter((candidate) => candidate.canMatchPartialContext(context, options));
+    }
+    /**
+     * Given a {@link ResourceJson.Json.IChildResourceCandidateDecl | child resource candidate declaration}, creates and adds a
+     * {@link Resources.ResourceCandidate | candidate} to the resource being built.
+     * @param candidate - The {@link ResourceJson.Json.IChildResourceCandidateDecl | IChildResourceCandidateDecl} to add to the
+     * resource being built.
+     * @returns `Success` with the added {@link Resources.ResourceCandidate | candidate} if successful,
+     * or `Failure` with an error message if not.
+     */
+    addChildCandidate(childDecl) {
+        return ResourceCandidate.create({
+            id: this.id,
+            resourceType: this._resourceType,
+            decl: childDecl,
+            conditionSets: this._conditionSets,
+            candidateValues: this._candidateValues
+        })
+            .withDetail('failure', 'success')
+            .onSuccess((candidate) => {
+            return this._candidates
+                .getOrAdd(candidate.conditions.toString(), candidate)
+                .onSuccess((added, detail) => {
+                if (detail === 'exists') {
+                    /* c8 ignore next 5 - defensive coding: conflicting candidates with same conditions should not occur */
+                    /* c8 ignore next 6 - functional code tested but coverage intermittently missed */
+                    if (!ResourceCandidate.equal(added, candidate)) {
+                        return failWithDetail(`${this.id}: conflicting candidates.`, 'exists');
+                    }
+                }
+                return succeedWithDetail(added, detail);
+            });
+        });
+    }
+    /**
+     * Given a {@link ResourceJson.Json.ILooseResourceCandidateDecl | resource candidate declaration}, creates and adds a
+     * {@link Resources.ResourceCandidate | candidate} to the resource being built.
+     * @param candidate - The {@link ResourceJson.Json.ILooseResourceCandidateDecl | IResourceCandidateDecl} to add to the
+     * resource being built.
+     * @returns `Success` with the added {@link Resources.ResourceCandidate | candidate} if successful,
+     * or `Failure` with an error message if not. Fails with error detail 'type-mismatch' if the candidate
+     * specifies a different resource type than previously added candidates, or with 'exists' if a candidate
+     * already exists with the same conditions but different values.  Succeeds with 'exists' and returns the
+     * existing candidate if the candidate to be added is identical to an existing candidate.
+     */
+    addLooseCandidate(decl) {
+        /* c8 ignore next 6 - functional code path tested but coverage intermittently missed */
+        if (decl.id !== this.id) {
+            return failWithDetail(`${this.id}: mismatched candidate id ${decl.id}.`, 'id-mismatch');
+        }
+        if (decl.resourceTypeName !== undefined) {
+            const rt = this.setResourceType(decl.resourceTypeName);
+            /* c8 ignore next 3 - functional code tested but coverage intermittently missed */
+            if (rt.isFailure()) {
+                return failWithDetail(rt.message, 'type-mismatch');
+            }
+        }
+        return this.addChildCandidate(decl);
+    }
+    /**
+     * Sets the resource type for the resource being built.  Fails if a resource type has already been set
+     * and it does not match the new resource type.
+     * @param resourceTypeName - The name of the resource type to set.
+     * @returns `Success` with the updated {@link Resources.ResourceBuilder | ResourceBuilder} object if successful,
+     * or `Failure` with an error message if not.
+     */
+    setResourceType(resourceTypeName) {
+        var _a;
+        /* c8 ignore next 2 - functional code tested but coverage intermittently missed */
+        if (((_a = this._resourceType) === null || _a === void 0 ? void 0 : _a.key) === resourceTypeName) {
+            return succeed(this);
+        }
+        else if (this._resourceType !== undefined) {
+            /* c8 ignore next 4 - functional code tested but coverage intermittently missed */
+            return fail(`${this.id}: conflicting resource types ${this._resourceType.key} !== ${resourceTypeName}.`);
+        }
+        return this._resourceTypes.validating.get(resourceTypeName).onSuccess((resourceType) => {
+            this._resourceType = resourceType;
+            return succeedWithDetail(this, 'success');
+        });
+    }
+    /**
+     * Builds the {@link Resources.Resource | resource} object from this builder.
+     * @returns `Success` with the new {@link Resources.Resource | Resource} object if successful,
+     * or `Failure` with an error message if not. Fails if no candidates have been added
+     * or if the resource type is not defined.
+     */
+    build() {
+        /* c8 ignore next 3 - functional code path tested but coverage intermittently missed */
+        if (this._candidates.size === 0) {
+            return fail(`${this.id}: no candidates supplied.`);
+        }
+        /* c8 ignore next 3 - functional code path tested but coverage intermittently missed */
+        if (this._resourceType === undefined) {
+            return fail(`${this.id}: no resource type supplied or inferred.`);
+        }
+        return Resource.create({
+            id: this.id,
+            resourceType: this._resourceType,
+            candidates: this.candidates,
+            decisions: this._decisions
+        });
+    }
+}
+//# sourceMappingURL=resourceBuilder.js.map

package/dist/packlets/resources/resourceCandidate.js

@@ -0,0 +1,216 @@
+/*
+ * 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 { PerfectMatch, Validate } from '../common';
+import { ConditionSet } from '../conditions';
+import * as ResourceJson from '../resource-json';
+import { captureResult, mapResults, MessageAggregator, fail, succeed } from '@fgv/ts-utils';
+/**
+ * A {@link Resources.ResourceCandidate | resource candidate} represents a single possible
+ * instance value for some resource, with the conditions under which it applies
+ * and instructions on how to merge it with other instances.
+ * @public
+ */
+export class ResourceCandidate {
+    /**
+     * The JSON representation of the instance data to be applied.
+     * @remarks
+     * This property provides access to the JSON data from the underlying candidate value.
+     */
+    get json() {
+        return this.candidateValue.json;
+    }
+    /**
+     * The completeness of the candidate value.
+     */
+    get completeness() {
+        return this.isPartial ? 'partial' : 'full';
+    }
+    /**
+     * Constructor for a {@link Resources.ResourceCandidate | ResourceCandidate} object.
+     * @param params - Parameters to create a new {@link Resources.ResourceCandidate | ResourceCandidate}.
+     * @public
+     */
+    constructor(params) {
+        var _a, _b;
+        this.id = Validate.toResourceId(params.id).orThrow();
+        this.candidateValue = params.candidateValues.validating.getOrAdd(params.decl.json).orThrow();
+        this.conditions = ResourceCandidate._mergeConditions(params.conditionSets, params.decl.conditions, params.parentConditions).orThrow();
+        this.isPartial = (_a = params.decl.isPartial) !== null && _a !== void 0 ? _a : false;
+        this.mergeMethod = (_b = params.decl.mergeMethod) !== null && _b !== void 0 ? _b : 'augment';
+        this.resourceType = params.resourceType;
+        if (this.resourceType) {
+            this.resourceType.validateDeclaration(this).orThrow();
+        }
+    }
+    /**
+     * Creates a new {@link Resources.ResourceCandidate | ResourceCandidate} object.
+     * @param params - Parameters to create a new {@link Resources.ResourceCandidate | ResourceCandidate}.
+     * @returns `Success` with the new {@link Resources.ResourceCandidate | ResourceCandidate} object if successful,
+     * or `Failure` with an error message if not.
+     * @public
+     */
+    static create(params) {
+        return captureResult(() => new ResourceCandidate(params));
+    }
+    /**
+     * Determines if this candidate can match the supplied context (possibly partial).
+     * @param context - The context to match.
+     * @param options - Options to use when matching.
+     * @returns `true` if the candidate can match the context, `false` otherwise.
+     */
+    canMatchPartialContext(context, options) {
+        return this.conditions.canMatchPartialContext(context, options);
+    }
+    /**
+     * Gets the {@link ResourceJson.Json.IChildResourceCandidateDecl | child resource candidate declaration}
+     * for this candidate.
+     * @param options - {@link ResourceJson.Helpers.IDeclarationOptions | options} to use when creating the declaration.
+     * @returns The {@link ResourceJson.Json.IChildResourceCandidateDecl | child resource candidate declaration}.
+     */
+    toChildResourceCandidateDecl(options) {
+        const showDefaults = (options === null || options === void 0 ? void 0 : options.showDefaults) === true;
+        return Object.assign(Object.assign({ json: this.json, conditions: this.conditions.toConditionSetRecordDecl(options) }, (showDefaults || this.isPartial ? { isPartial: this.isPartial } : {})), (showDefaults || this.mergeMethod !== 'augment' ? { mergeMethod: this.mergeMethod } : {}));
+    }
+    /**
+     * Gets the {@link ResourceJson.Json.ILooseResourceCandidateDecl | loose resource candidate declaration}
+     * for this candidate.
+     * @param options - {@link ResourceJson.Helpers.IDeclarationOptions | options} to use when creating the declaration.
+     * @returns The {@link ResourceJson.Json.ILooseResourceCandidateDecl | loose resource candidate declaration}.
+     */
+    toLooseResourceCandidateDecl(options) {
+        var _a;
+        const showDefaults = (options === null || options === void 0 ? void 0 : options.showDefaults) === true;
+        const resourceTypeName = (_a = this.resourceType) === null || _a === void 0 ? void 0 : _a.key;
+        return Object.assign(Object.assign(Object.assign({ id: this.id.toString(), json: this.json, conditions: this.conditions.toConditionSetRecordDecl(options) }, (showDefaults || this.isPartial ? { isPartial: this.isPartial } : {})), (showDefaults || this.mergeMethod !== 'augment' ? { mergeMethod: this.mergeMethod } : {})), (resourceTypeName ? { resourceTypeName } : {}));
+    }
+    /**
+     * Extracts the {@link ResourceTypes.ResourceType | resource type} from a list of {@link Resources.ResourceCandidate | resource candidates},
+     * if present.
+     * @param candidates - The list of candidates from which to extract the resource type.
+     * @returns `Success` with the resource type if successful, `Success` with `undefined` if none of the candidates
+     * specify a resource tap, and `Failure` with an error message if clients specify conflicting resource types.
+     * @public
+     */
+    static validateResourceTypes(candidates, expectedType) {
+        const errors = new MessageAggregator();
+        let selectedType = expectedType;
+        for (const candidate of candidates) {
+            if (selectedType === undefined) {
+                /* c8 ignore next 1 - functional code path tested but coverage intermittently missed */
+                selectedType = candidate.resourceType;
+            }
+            else if (candidate.resourceType && selectedType !== candidate.resourceType) {
+                /* c8 ignore next 4 - functional code path tested but coverage intermittently missed */
+                errors.addMessage(`${candidate.id}: resource type mismatch (${selectedType.key} != ${candidate.resourceType.key})`);
+            }
+        }
+        return errors.returnOrReport(succeed(selectedType));
+    }
+    /**
+     * Compares two {@link Resources.ResourceCandidate | ResourceCandidates} for sorting purposes.
+     * @param rc1 - The first candidate to compare.
+     * @param rc2 - The second candidate to compare.
+     * @returns A negative number if `rc1` should come before `rc2`, a positive number if `rc2` should come before `rc1`,
+     * or zero if they are equivalent.
+     * @public
+     */
+    static compare(rc1, rc2) {
+        return ConditionSet.compare(rc1.conditions, rc2.conditions);
+    }
+    /**
+     * Compares two {@link Resources.ResourceCandidate | ResourceCandidates} for equality.
+     * @param rc1 - The first candidate to compare.
+     * @param rc2 - The second candidate to compare.
+     * @returns `true` if the candidates are equal, `false` otherwise.
+     * @public
+     */
+    static equal(rc1, rc2) {
+        /* c8 ignore next 3 - functional code path tested but coverage intermittently missed */
+        if (rc1 === rc2) {
+            return true;
+        }
+        let equal = rc1.id === rc2.id &&
+            rc1.isPartial === rc2.isPartial &&
+            rc1.mergeMethod === rc2.mergeMethod &&
+            ConditionSet.compare(rc1.conditions, rc2.conditions) === 0;
+        if (equal) {
+            // Compare candidate values by their keys for efficient JSON comparison
+            equal = rc1.candidateValue.key === rc2.candidateValue.key;
+        }
+        return equal;
+    }
+    /**
+     * Validates declared conditions and merges them with parent conditions.
+     * @param conditionSets - The {@link Conditions.ConditionSetCollector | condition set collector}
+     * to use for this candidate.
+     * @param declared - The declared conditions for the candidate.
+     * @param parent - The parent conditions to merge with the declared conditions.
+     * @returns `Success` with the merged conditions if successful, `Failure` otherwise.
+     * @internal
+     */
+    static _mergeConditions(conditionSets, declared, parent) {
+        /* c8 ignore next 2 - code coverage is flaky */
+        declared = declared !== null && declared !== void 0 ? declared : {};
+        parent = parent !== null && parent !== void 0 ? parent : [];
+        const { value: conditionDecls, message } = ResourceJson.Convert.conditionSetDecl.convert(declared);
+        /* c8 ignore next 3 - functional code path tested but coverage intermittently missed */
+        if (message !== undefined) {
+            return fail(message);
+        }
+        return mapResults(
+        // get or add all declared conditions from our condition collector
+        conditionDecls.map((decl) => conditionSets.conditions.validating.getOrAdd(decl))).onSuccess((declaredConditions) => {
+            // make sure our parent conditions all come from our condition collector too
+            return mapResults(parent.map((c) => conditionSets.conditions.getOrAdd(c))).onSuccess((parentConditions) => {
+                const conditions = [...parentConditions, ...declaredConditions];
+                return conditionSets.validating.getOrAdd(conditions);
+            });
+        });
+    }
+    /**
+     * Finds the qualifiers that are made irrelevant by the supplied filterForContext.
+     * @param candidates - The candidates to find the reducible qualifiers for.
+     * @param filterForContext - The filter for context to use.
+     * @returns The qualifiers that are made irrelevant by the filterForContext.
+     * @remarks
+     * For any given set of candidates, qualifiers that match every candidate perfectly
+     * are irrelevant to the filtered content and can be removed.  Qualifiers that do not
+     * match, that are not in the filterForContext, or which partially match at least one
+     * candidate remain relevant and must not be removed.
+     * @public
+     */
+    static findReducibleQualifiers(candidates, filterForContext) {
+        const qualifiersToReduce = new Set(Object.keys(filterForContext));
+        for (const candidate of candidates) {
+            for (const condition of candidate.conditions.conditions) {
+                if (qualifiersToReduce.has(condition.qualifier.name)) {
+                    const match = condition.qualifier.type.matches(condition.value, filterForContext[condition.qualifier.name], 'matches');
+                    if (match !== PerfectMatch) {
+                        qualifiersToReduce.delete(condition.qualifier.name);
+                    }
+                }
+            }
+        }
+        return qualifiersToReduce.size > 0 ? qualifiersToReduce : undefined;
+    }
+}
+//# sourceMappingURL=resourceCandidate.js.map