@fgv/ts-res 4.5.0-3 → 5.0.0-10

package/lib/packlets/qualifier-types/literalValueHierarchy.js

@@ -0,0 +1,228 @@
+"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.LiteralValueHierarchy = void 0;
+const ts_utils_1 = require("@fgv/ts-utils");
+const common_1 = require("../common");
+/**
+ * A class that implements a hierarchy of literal values. The hierarchy is defined as a
+ * tree, where each value can have multiple children but only one parent. The root of the
+ * tree has no parent. The hierarchy is used to determine the relationship between values
+ * when matching conditions and contexts.
+ *
+ * @remarks
+ * The hierarchy can be created in two modes:
+ * - **Constrained mode**: When enumerated values are provided, only those values are allowed
+ *   in the hierarchy and matching operations.
+ * - **Open values mode**: When no enumerated values are provided, all values referenced in
+ *   the hierarchy are automatically collected and used. This allows for flexible hierarchies
+ *   where any value can be used in matching operations.
+ * @public
+ */
+class LiteralValueHierarchy {
+    constructor(params) {
+        const result = LiteralValueHierarchy._buildValuesFromHierarchy(params);
+        this.values = result.orThrow();
+        this.isOpenValues = !params.values || params.values.length === 0;
+    }
+    /**
+     * Creates a new {@link QualifierTypes.LiteralValueHierarchy | LiteralValueHierarchy} instance.
+     * @param params - The {@link QualifierTypes.ILiteralValueHierarchyCreateParams | parameters}
+     * used to create the hierarchy.
+     * @returns `Success` with the new hierarchy or `Failure` with an error message.
+     */
+    static create(params) {
+        return (0, ts_utils_1.captureResult)(() => new LiteralValueHierarchy(params));
+    }
+    /**
+     * Checks if a value exists in the hierarchy.
+     * @param value - The value to check.
+     * @returns `true` if the value exists in the hierarchy, `false` otherwise.
+     */
+    hasValue(value) {
+        return this.values.has(value);
+    }
+    /**
+     * Gets all root values (values with no parent) in the hierarchy.
+     * @returns `Success` with an array of root values.
+     */
+    getRoots() {
+        return (0, ts_utils_1.succeed)(Array.from(this.values.values())
+            .filter((v) => !v.parent)
+            .map((v) => v.name));
+    }
+    /**
+     * Gets all ancestors of a value in the hierarchy.
+     * @param value - The value to get ancestors for.
+     * @returns `Success` with an array of ancestor values, ordered from immediate parent
+     * to root, or `Failure` if the value is not in the hierarchy.
+     */
+    getAncestors(value) {
+        const current = this.values.get(value);
+        /* c8 ignore next 3 - functional error case tested but coverage intermittently missed */
+        if (!current) {
+            return (0, ts_utils_1.fail)(`${value}: not found in hierarchy`);
+        }
+        const ancestors = [];
+        let ancestor = current.parent;
+        while (ancestor) {
+            ancestors.push(ancestor.name);
+            ancestor = ancestor.parent;
+        }
+        return (0, ts_utils_1.succeed)(ancestors);
+    }
+    /**
+     * Determines if a value is an ancestor of a possible ancestor value.
+     * @param value - The value to check.
+     * @param possibleAncestor - The possible ancestor value.
+     * @returns `true` if the value is an ancestor of the possible ancestor, `false` otherwise.
+     */
+    isAncestor(value, possibleAncestor) {
+        const ancestors = this.getAncestors(value);
+        if (ancestors.isSuccess()) {
+            return ancestors.value.includes(possibleAncestor);
+        }
+        return false;
+    }
+    /**
+     * Gets all descendants of a value in the hierarchy.
+     * @param value - The value to get descendants for.
+     * @returns `Success` with an array of descendant values, or `Failure` if the value
+     * is not in the hierarchy.
+     */
+    getDescendants(value) {
+        const current = this.values.get(value);
+        if (!current) {
+            return (0, ts_utils_1.fail)(`${value}: not found in hierarchy`);
+        }
+        const descendants = [];
+        if (current.children) {
+            for (const childName of current.children) {
+                descendants.push(childName);
+                const childDescendants = this.getDescendants(childName);
+                if (childDescendants.isSuccess()) {
+                    descendants.push(...childDescendants.value);
+                }
+            }
+        }
+        return (0, ts_utils_1.succeed)(descendants);
+    }
+    match(condition, context, __operator) {
+        var _a;
+        // For open hierarchies, skip validation and allow any values
+        if (!this.isOpenValues) {
+            // Validate that both condition and context exist in the hierarchy
+            /* c8 ignore next 2 - functional error case tested but coverage intermittently missed */
+            if (!this.values.has(condition)) {
+                return common_1.NoMatch;
+            }
+            /* c8 ignore next 2 - functional error case tested but coverage intermittently missed */
+            if (!this.values.has(context)) {
+                return common_1.NoMatch;
+            }
+        }
+        if (condition === context) {
+            return common_1.PerfectMatch;
+        }
+        // For open hierarchies, if values aren't in the hierarchy, treat as no match
+        // but don't fail validation
+        const values = this.values;
+        /* c8 ignore next 1 - ? is defense in depth */
+        let value = (_a = values.get(context)) === null || _a === void 0 ? void 0 : _a.parent;
+        /* c8 ignore next 2 - functional error case tested but coverage intermittently missed */
+        if (!value) {
+            return common_1.NoMatch;
+        }
+        let score = common_1.PerfectMatch;
+        while (value) {
+            score *= 0.9;
+            if (value.name === condition) {
+                return common_1.Convert.qualifierMatchScore.convert(score).orDefault(common_1.NoMatch);
+            }
+            value = value.parent;
+        }
+        return common_1.NoMatch;
+    }
+    static _buildValuesFromHierarchy(params) {
+        var _a;
+        const errors = new ts_utils_1.MessageAggregator();
+        const values = params.values;
+        const hierarchy = (_a = params.hierarchy) !== null && _a !== void 0 ? _a : {};
+        // If no values are provided, collect all values from the hierarchy
+        let allValues;
+        if (!values || values.length === 0) {
+            const hierarchyValues = new Set();
+            // Add all keys and values from the hierarchy
+            Object.keys(hierarchy).forEach((key) => hierarchyValues.add(key));
+            Object.values(hierarchy).forEach((value) => hierarchyValues.add(value));
+            allValues = Array.from(hierarchyValues);
+        }
+        else {
+            allValues = [...values];
+        }
+        const valueMap = new Map(allValues.map((name) => [name, { name }]));
+        if (hierarchy) {
+            for (const [valueName, parentName] of Object.entries(hierarchy)) {
+                const value = valueMap.get(valueName);
+                if (!value) {
+                    errors.addMessage(`${valueName}: invalid literal value.`);
+                    continue;
+                }
+                const parent = valueMap.get(parentName);
+                if (!parent) {
+                    errors.addMessage(`${valueName}: parent ${parentName} is not a valid literal value.`);
+                    continue;
+                }
+                let ancestor = parent.parent;
+                let circular = false;
+                const ancestors = [];
+                while (ancestor) {
+                    /* c8 ignore next 1 - defensive coding: complex circular reference detection intermittently missed */
+                    ancestors.push(ancestor.name);
+                    /* c8 ignore next 1 - defensive coding: ancestor.parent === value is very difficult to reach */
+                    if (ancestor.parent === parent || ancestor.parent === value) {
+                        /* c8 ignore next 3 - defensive coding: circular reference error reporting intermittently missed */
+                        errors.addMessage(`${valueName}: Circular reference detected: ${ancestors.join('->')}`);
+                        circular = true;
+                        break;
+                    }
+                    ancestor = ancestor.parent;
+                }
+                /* c8 ignore next 2 - defensive coding: circular reference handling intermittently missed */
+                if (circular) {
+                    continue;
+                }
+                value.parent = parent;
+                if (parent.children) {
+                    parent.children.push(value.name);
+                }
+                else {
+                    parent.children = [value.name];
+                }
+            }
+        }
+        return errors.returnOrReport((0, ts_utils_1.succeed)(valueMap));
+    }
+}
+exports.LiteralValueHierarchy = LiteralValueHierarchy;
+//# sourceMappingURL=literalValueHierarchy.js.map

package/lib/packlets/qualifier-types/literalValueHierarchy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"literalValueHierarchy.js","sourceRoot":"","sources":["../../../src/packlets/qualifier-types/literalValueHierarchy.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 { captureResult, MessageAggregator, Result, succeed, fail } from '@fgv/ts-utils';\nimport {\n  ConditionOperator,\n  NoMatch,\n  PerfectMatch,\n  QualifierConditionValue,\n  QualifierContextValue,\n  QualifierMatchScore,\n  Convert as CommonConverters\n} from '../common';\n\n/**\n * Declares a hierarchy of literal values. The keys are the names of the values, and the\n * values are the names of their parents.\n * @remarks\n * The hierarchy is defined as a tree, where each value can have multiple children but\n * only one parent. The root of the tree has no parent. The hierarchy is used to\n * determine the relationship between values when matching conditions and contexts.\n * @public\n */\nexport type LiteralValueHierarchyDecl<T extends string> = Partial<Record<T, T>>;\n\n/**\n * Describes a single valid literal value including optional parent and child values.\n * @public\n */\nexport interface ILiteralValue<T extends string> {\n  readonly name: T;\n  readonly parent?: ILiteralValue<T>;\n  readonly children?: ReadonlyArray<T>;\n}\n\n/**\n * Describes the parameters used to create a new\n * {@link QualifierTypes.LiteralValueHierarchy | LiteralValueHierarchy}.\n * @public\n */\nexport interface ILiteralValueHierarchyCreateParams<T extends string = string> {\n  values: ReadonlyArray<T>;\n  hierarchy?: LiteralValueHierarchyDecl<T>;\n}\n\n/**\n * Internal interface used during hierarchy construction to build\n * {@link QualifierTypes.ILiteralValue | ILiteralValue} objects.\n * @public\n */\ninterface ILiteralValueBuilder<T extends string> {\n  readonly name: T;\n  parent?: ILiteralValue<T>;\n  children?: T[];\n}\n\n/**\n * A class that implements a hierarchy of literal values. The hierarchy is defined as a\n * tree, where each value can have multiple children but only one parent. The root of the\n * tree has no parent. The hierarchy is used to determine the relationship between values\n * when matching conditions and contexts.\n *\n * @remarks\n * The hierarchy can be created in two modes:\n * - **Constrained mode**: When enumerated values are provided, only those values are allowed\n *   in the hierarchy and matching operations.\n * - **Open values mode**: When no enumerated values are provided, all values referenced in\n *   the hierarchy are automatically collected and used. This allows for flexible hierarchies\n *   where any value can be used in matching operations.\n * @public\n */\nexport class LiteralValueHierarchy<T extends string = string> {\n  /**\n   * A map of all allowed literal values to the corresponding\n   * {@link QualifierTypes.ILiteralValue | ILiteralValue} validated definition.\n   */\n  public readonly values: ReadonlyMap<T, ILiteralValue<T>>;\n\n  /**\n   * Indicates whether this hierarchy was created with open values (no enumerated values\n   * provided), allowing any value to be used in matching operations.\n   */\n  public readonly isOpenValues: boolean;\n\n  protected constructor(params: ILiteralValueHierarchyCreateParams<T>) {\n    const result = LiteralValueHierarchy._buildValuesFromHierarchy(params);\n    this.values = result.orThrow();\n    this.isOpenValues = !params.values || params.values.length === 0;\n  }\n\n  /**\n   * Creates a new {@link QualifierTypes.LiteralValueHierarchy | LiteralValueHierarchy} instance.\n   * @param params - The {@link QualifierTypes.ILiteralValueHierarchyCreateParams | parameters}\n   * used to create the hierarchy.\n   * @returns `Success` with the new hierarchy or `Failure` with an error message.\n   */\n  public static create<T extends string>(\n    params: ILiteralValueHierarchyCreateParams<T>\n  ): Result<LiteralValueHierarchy<T>> {\n    return captureResult(() => new LiteralValueHierarchy(params));\n  }\n\n  /**\n   * Checks if a value exists in the hierarchy.\n   * @param value - The value to check.\n   * @returns `true` if the value exists in the hierarchy, `false` otherwise.\n   */\n  public hasValue(value: T): boolean {\n    return this.values.has(value);\n  }\n\n  /**\n   * Gets all root values (values with no parent) in the hierarchy.\n   * @returns `Success` with an array of root values.\n   */\n  public getRoots(): Result<T[]> {\n    return succeed(\n      Array.from(this.values.values())\n        .filter((v) => !v.parent)\n        .map((v) => v.name)\n    );\n  }\n\n  /**\n   * Gets all ancestors of a value in the hierarchy.\n   * @param value - The value to get ancestors for.\n   * @returns `Success` with an array of ancestor values, ordered from immediate parent\n   * to root, or `Failure` if the value is not in the hierarchy.\n   */\n  public getAncestors(value: T): Result<T[]> {\n    const current = this.values.get(value);\n    /* c8 ignore next 3 - functional error case tested but coverage intermittently missed */\n    if (!current) {\n      return fail(`${value}: not found in hierarchy`);\n    }\n\n    const ancestors: T[] = [];\n    let ancestor = current.parent;\n\n    while (ancestor) {\n      ancestors.push(ancestor.name);\n      ancestor = ancestor.parent;\n    }\n\n    return succeed(ancestors);\n  }\n\n  /**\n   * Determines if a value is an ancestor of a possible ancestor value.\n   * @param value - The value to check.\n   * @param possibleAncestor - The possible ancestor value.\n   * @returns `true` if the value is an ancestor of the possible ancestor, `false` otherwise.\n   */\n  public isAncestor(value: T, possibleAncestor: T): boolean {\n    const ancestors = this.getAncestors(value);\n    if (ancestors.isSuccess()) {\n      return ancestors.value.includes(possibleAncestor);\n    }\n    return false;\n  }\n\n  /**\n   * Gets all descendants of a value in the hierarchy.\n   * @param value - The value to get descendants for.\n   * @returns `Success` with an array of descendant values, or `Failure` if the value\n   * is not in the hierarchy.\n   */\n  public getDescendants(value: T): Result<T[]> {\n    const current = this.values.get(value);\n    if (!current) {\n      return fail(`${value}: not found in hierarchy`);\n    }\n\n    const descendants: T[] = [];\n    if (current.children) {\n      for (const childName of current.children) {\n        descendants.push(childName);\n        const childDescendants = this.getDescendants(childName);\n        if (childDescendants.isSuccess()) {\n          descendants.push(...childDescendants.value);\n        }\n      }\n    }\n\n    return succeed(descendants);\n  }\n\n  public match(condition: T, context: T): QualifierMatchScore;\n  /**\n   * Matches a condition value against a context value, where an exact match of the\n   * condition and context returns {@link PerfectMatch | PerfectMatch}, a condition\n   * value that does not match the context value or any of its ancestors returns\n   * {@link NoMatch | NoMatch}, and a condition value that matches the context value\n   * or any of its ancestors returns a positive score that is less than\n   * {@link PerfectMatch | PerfectMatch}, with the score decreasing with each ancestor\n   * in the hierarchy.\n   * @param condition - The condition value to match.\n   * @param context - The context value to match against.\n   * @param __operator - The operator used for matching (not used in this implementation).\n   * @returns A {@link QualifierMatchScore | QualifierMatchScore} indicating the match score.\n   */\n  public match(\n    condition: QualifierConditionValue,\n    context: QualifierContextValue,\n    __operator?: ConditionOperator\n  ): QualifierMatchScore;\n  public match(condition: string, context: string, __operator?: ConditionOperator): QualifierMatchScore {\n    // For open hierarchies, skip validation and allow any values\n    if (!this.isOpenValues) {\n      // Validate that both condition and context exist in the hierarchy\n      /* c8 ignore next 2 - functional error case tested but coverage intermittently missed */\n      if (!this.values.has(condition as T)) {\n        return NoMatch;\n      }\n      /* c8 ignore next 2 - functional error case tested but coverage intermittently missed */\n      if (!this.values.has(context as T)) {\n        return NoMatch;\n      }\n    }\n\n    if ((condition as string) === (context as string)) {\n      return PerfectMatch;\n    }\n\n    // For open hierarchies, if values aren't in the hierarchy, treat as no match\n    // but don't fail validation\n    const values: ReadonlyMap<string, ILiteralValue<string>> = this.values;\n    /* c8 ignore next 1 - ? is defense in depth */\n    let value = values.get(context)?.parent;\n    /* c8 ignore next 2 - functional error case tested but coverage intermittently missed */\n    if (!value) {\n      return NoMatch;\n    }\n    let score = PerfectMatch as number;\n    while (value) {\n      score *= 0.9;\n      if (value.name === condition) {\n        return CommonConverters.qualifierMatchScore.convert(score).orDefault(NoMatch);\n      }\n      value = value.parent;\n    }\n    return NoMatch;\n  }\n\n  protected static _buildValuesFromHierarchy<T extends string>(\n    params: ILiteralValueHierarchyCreateParams<T>\n  ): Result<ReadonlyMap<T, ILiteralValue<T>>> {\n    const errors = new MessageAggregator();\n    const values = params.values;\n    const hierarchy = params.hierarchy ?? {};\n\n    // If no values are provided, collect all values from the hierarchy\n    let allValues: T[];\n    if (!values || values.length === 0) {\n      const hierarchyValues = new Set<T>();\n      // Add all keys and values from the hierarchy\n      Object.keys(hierarchy).forEach((key) => hierarchyValues.add(key as T));\n      Object.values(hierarchy).forEach((value) => hierarchyValues.add(value as T));\n      allValues = Array.from(hierarchyValues);\n    } else {\n      allValues = [...values];\n    }\n\n    const valueMap = new Map<T, ILiteralValueBuilder<T>>(allValues.map((name) => [name, { name }]));\n\n    if (hierarchy) {\n      for (const [valueName, parentName] of Object.entries(hierarchy)) {\n        const value = valueMap.get(valueName as T);\n        if (!value) {\n          errors.addMessage(`${valueName}: invalid literal value.`);\n          continue;\n        }\n\n        const parent = valueMap.get(parentName as T);\n        if (!parent) {\n          errors.addMessage(`${valueName}: parent ${parentName} is not a valid literal value.`);\n          continue;\n        }\n\n        let ancestor = parent.parent;\n        let circular = false;\n        const ancestors: T[] = [];\n\n        while (ancestor) {\n          /* c8 ignore next 1 - defensive coding: complex circular reference detection intermittently missed */\n          ancestors.push(ancestor.name);\n          /* c8 ignore next 1 - defensive coding: ancestor.parent === value is very difficult to reach */\n          if (ancestor.parent === parent || ancestor.parent === value) {\n            /* c8 ignore next 3 - defensive coding: circular reference error reporting intermittently missed */\n            errors.addMessage(`${valueName}: Circular reference detected: ${ancestors.join('->')}`);\n            circular = true;\n            break;\n          }\n          ancestor = ancestor.parent;\n        }\n\n        /* c8 ignore next 2 - defensive coding: circular reference handling intermittently missed */\n        if (circular) {\n          continue;\n        }\n\n        value.parent = parent;\n        if (parent.children) {\n          parent.children.push(value.name);\n        } else {\n          parent.children = [value.name];\n        }\n      }\n    }\n\n    return errors.returnOrReport(succeed(valueMap));\n  }\n}\n"]}

package/lib/packlets/qualifier-types/qualifierType.d.ts

@@ -23,17 +23,26 @@ export interface IQualifierType extends ICollectible<QualifierTypeName, Qualifie
     /**
      * Validates a condition value for this qualifier type.
      * @param value - The string value to validate.
-     * @returns `Success` with the {@link QualifierConditionValue | validated value} if the value
-     * is valid for use in a condition, `Failure` with error details otherwise.
+     * @returns `Success` with the {@link QualifierConditionValue | validated value}
+     * if the value is valid for use in a condition, `Failure` with error details
+     * otherwise.
      */
     isValidConditionValue(value: string): value is QualifierConditionValue;
     /**
      * Validates a context value for this qualifier type.
      * @param value - The string value to validate.
-     * @returns `Success` with the {@link QualifierContextValue | validated value} if the value
-     * is valid for use in a runtime context, `Failure` with error details otherwise.
+     * @returns `Success` with the {@link QualifierContextValue | validated value}
+     * if the value is valid for use in a runtime context, `Failure` with error
+     * details otherwise.
      */
     isValidContextValue(value: string): value is QualifierContextValue;
+    /**
+     * Determines if a supplied condition value is a potential match for a possible context value.
+     * @param conditionValue - The condition value.
+     * @param contextValue - The context value.
+     * @returns `true` if the condition value is a potential match for the context value, `false` otherwise.
+     */
+    isPotentialMatch(conditionValue: string, contextValue: string): boolean;
     /**
      * Validates that a value and optional operator are valid for use in a condition
      * for qualifiers of this type.
@@ -42,24 +51,26 @@ export interface IQualifierType extends ICollectible<QualifierTypeName, Qualifie
      */
     validateCondition(value: string, operator?: ConditionOperator): Result<QualifierConditionValue>;
     /**
-     * Validates that a value is valid for use in a runtime context for qualifiers of this type.
+     * Validates that a value is valid for use in a runtime context for qualifiers
+     * of this type.
      * @param value - The string value to validate.
-     * @returns `Success` with the {@link QualifierContextValue | validated value} if the value
-     * is valid for use in a runtime context, `Failure` with error details otherwise.
+     * @returns `Success` with the {@link QualifierContextValue | validated value}
+     * if the value is valid for use in a runtime context, `Failure` with error
+     * details otherwise.
      */
     validateContextValue(value: string): Result<QualifierContextValue>;
     /**
-     * Determines the extent to which a condition matches a context value for this qualifier type.
+     * Determines the extent to which a condition matches a context value for this
+     * qualifier type.
      * @param condition - The condition value to evaluate.
      * @param context - The context value to evaluate.
      * @param operator - The operator to use in evaluating the match.
-     * @returns a {@link QualifierMatchScore | score} indicating the extent to which the condition
-     * matches the context value.
+     * @returns a {@link QualifierMatchScore | score} indicating the extent to which
+     * the condition matches the context value.
      */
     matches(condition: QualifierConditionValue, context: QualifierContextValue, operator: ConditionOperator): QualifierMatchScore;
     /**
-     * Sets the index for this qualifier type.  Once set, index is
-     * immutable.
+     * Sets the index for this qualifier type. Once set, index is immutable.
      */
     setIndex(index: number): Result<QualifierTypeIndex>;
 }
@@ -121,6 +132,10 @@ export declare abstract class QualifierType implements IQualifierType {
      * {@inheritdoc QualifierTypes.IQualifierType.isValidContextValue}
      */
     isValidContextValue(value: string): value is QualifierContextValue;
+    /**
+     * {@inheritdoc QualifierTypes.IQualifierType.isPotentialMatch}
+     */
+    isPotentialMatch(conditionValue: string, contextValue: string): boolean;
     /**
      * {@inheritdoc QualifierTypes.IQualifierType.validateCondition}
      */
@@ -157,8 +172,8 @@ export declare abstract class QualifierType implements IQualifierType {
      * @param condition - The {@link QualifierConditionValue | condition value} to match.
      * @param context - The {@link QualifierContextValue | context value} to match.
      * @param operator - The {@link ConditionOperator | operator} to use in the match.
-     * @returns a {@link QualifierMatchScore | score} indicating the extent to which the condition
-     * matches the context value.
+     * @returns a {@link QualifierMatchScore | score} indicating the extent to which
+     * the condition matches the context value.
      * @public
      */
     protected abstract _matchOne(condition: QualifierConditionValue, context: QualifierContextValue, operator: ConditionOperator): QualifierMatchScore;
@@ -167,14 +182,14 @@ export declare abstract class QualifierType implements IQualifierType {
      * @param condition - The {@link QualifierConditionValue | condition value} to match.
      * @param context - The comma-separated list of {@link QualifierContextValue | context values} to match.
      * @param operator - The {@link ConditionOperator | operator} to use in the match.
-     * @returns a {@link QualifierMatchScore | score} indicating the extent to which the condition
-     * matches the context value.
+     * @returns a {@link QualifierMatchScore | score} indicating the extent to which
+     * the condition matches the context value.
      * @public
      */
     protected _matchList(condition: QualifierConditionValue, context: QualifierContextValue[], operator: ConditionOperator): QualifierMatchScore;
     /**
-     * Splits a comma-separated {@link QualifierContextValue | context value} into an array of
-     * individual values.
+     * Splits a comma-separated {@link QualifierContextValue | context value} into an
+     * array of individual values.
      * @param value - The value to split.
      * @returns an array of individual context values.
      * @public

package/lib/packlets/qualifier-types/qualifierType.d.ts.map

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

package/lib/packlets/qualifier-types/qualifierType.js

@@ -65,8 +65,19 @@ class QualifierType {
             return true;
         }
         if (this.allowContextList) {
+            /* c8 ignore next 1 - functional code tested but coverage intermittently missed */
             return value.split(',').every((v) => this.isValidConditionValue(v.trim()));
         }
+        /* c8 ignore next 1 - functional code tested but coverage intermittently missed */
+        return false;
+    }
+    /**
+     * {@inheritdoc QualifierTypes.IQualifierType.isPotentialMatch}
+     */
+    isPotentialMatch(conditionValue, contextValue) {
+        if (this.isValidConditionValue(conditionValue) && this.isValidContextValue(contextValue)) {
+            return this._matchOne(conditionValue, contextValue, 'matches') !== common_1.NoMatch;
+        }
         return false;
     }
     /**
@@ -74,8 +85,10 @@ class QualifierType {
      */
     validateCondition(value, operator) {
         operator = operator !== null && operator !== void 0 ? operator : 'matches';
+        /* c8 ignore next 2 - functional error case tested but coverage intermittently missed */
         if (operator !== 'matches') {
             return (0, ts_utils_1.fail)(`${operator}: invalid condition operator`);
+            /* c8 ignore next 2 - functional error case tested but coverage intermittently missed */
         }
         else if (!this.isValidConditionValue(value)) {
             return (0, ts_utils_1.fail)(`${value}: invalid condition value for qualifierType ${this.name}`);
@@ -86,6 +99,7 @@ class QualifierType {
      * {@inheritdoc QualifierTypes.IQualifierType.validateContextValue}
      */
     validateContextValue(value) {
+        /* c8 ignore next 2 - functional error case tested but coverage intermittently missed */
         if (!this.isValidContextValue(value)) {
             return (0, ts_utils_1.fail)(`${value}: invalid context value for qualifierType ${this.name}`);
         }
@@ -139,8 +153,8 @@ class QualifierType {
      * @param condition - The {@link QualifierConditionValue | condition value} to match.
      * @param context - The comma-separated list of {@link QualifierContextValue | context values} to match.
      * @param operator - The {@link ConditionOperator | operator} to use in the match.
-     * @returns a {@link QualifierMatchScore | score} indicating the extent to which the condition
-     * matches the context value.
+     * @returns a {@link QualifierMatchScore | score} indicating the extent to which
+     * the condition matches the context value.
      * @public
      */
     _matchList(condition, context, operator) {
@@ -159,8 +173,8 @@ class QualifierType {
         return common_1.NoMatch;
     }
     /**
-     * Splits a comma-separated {@link QualifierContextValue | context value} into an array of
-     * individual values.
+     * Splits a comma-separated {@link QualifierContextValue | context value} into an
+     * array of individual values.
      * @param value - The value to split.
      * @returns an array of individual context values.
      * @public

package/lib/packlets/qualifier-types/qualifierType.js.map

@@ -1 +1 @@
-{"version":3,"file":"qualifierType.js","sourceRoot":"","sources":["../../../src/packlets/qualifier-types/qualifierType.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 { Collections, ICollectible, Result, fail, succeed } from '@fgv/ts-utils';\nimport {\n  ConditionOperator,\n  Convert,\n  NoMatch,\n  PerfectMatch,\n  QualifierConditionValue,\n  QualifierContextValue,\n  QualifierMatchScore,\n  QualifierTypeIndex,\n  QualifierTypeName,\n  Validate\n} from '../common';\n\n/**\n * Interface for a qualifier type. A qualifier type implements the build and\n * runtime semantics for some class of related qualifiers (e.g. language,\n * territories, etc).\n * @public\n */\nexport interface IQualifierType extends ICollectible<QualifierTypeName, QualifierTypeIndex> {\n  /**\n   * The name of the qualifier type.\n   */\n  readonly name: QualifierTypeName;\n\n  /**\n   * Unique key for this qualifier.\n   */\n  readonly key: QualifierTypeName;\n\n  /**\n   * Global index for this qualifier type. Immutable once set, either at\n   * construction or using {@link QualifierTypes.IQualifierType.setIndex | setIndex}.\n   */\n  readonly index: QualifierTypeIndex | undefined;\n\n  /**\n   * Validates a condition value for this qualifier type.\n   * @param value - The string value to validate.\n   * @returns `Success` with the {@link QualifierConditionValue | validated value} if the value\n   * is valid for use in a condition, `Failure` with error details otherwise.\n   */\n  isValidConditionValue(value: string): value is QualifierConditionValue;\n\n  /**\n   * Validates a context value for this qualifier type.\n   * @param value - The string value to validate.\n   * @returns `Success` with the {@link QualifierContextValue | validated value} if the value\n   * is valid for use in a runtime context, `Failure` with error details otherwise.\n   */\n  isValidContextValue(value: string): value is QualifierContextValue;\n\n  /**\n   * Validates that a value and optional operator are valid for use in a condition\n   * for qualifiers of this type.\n   * @param value - The string value to validate.\n   * @param operator - An optional operator to validate. Defaults to 'matches'.\n   */\n  validateCondition(value: string, operator?: ConditionOperator): Result<QualifierConditionValue>;\n\n  /**\n   * Validates that a value is valid for use in a runtime context for qualifiers of this type.\n   * @param value - The string value to validate.\n   * @returns `Success` with the {@link QualifierContextValue | validated value} if the value\n   * is valid for use in a runtime context, `Failure` with error details otherwise.\n   */\n  validateContextValue(value: string): Result<QualifierContextValue>;\n\n  /**\n   * Determines the extent to which a condition matches a context value for this qualifier type.\n   * @param condition - The condition value to evaluate.\n   * @param context - The context value to evaluate.\n   * @param operator - The operator to use in evaluating the match.\n   * @returns a {@link QualifierMatchScore | score} indicating the extent to which the condition\n   * matches the context value.\n   */\n  matches(\n    condition: QualifierConditionValue,\n    context: QualifierContextValue,\n    operator: ConditionOperator\n  ): QualifierMatchScore;\n\n  /**\n   * Sets the index for this qualifier type.  Once set, index is\n   * immutable.\n   */\n  setIndex(index: number): Result<QualifierTypeIndex>;\n}\n\n/**\n * Parameters used to create a base {@link QualifierTypes.QualifierType | qualifier type}.\n * @public\n */\nexport interface IQualifierTypeCreateParams {\n  /**\n   * The name of the qualifier type. No default value.\n   */\n  name: string;\n\n  /**\n   * Global index for this qualifier type.\n   */\n  index?: number;\n\n  /**\n   * Flag indicating whether this qualifier type allows a list of values in a context.\n   * Defaults to `false`.\n   */\n  allowContextList?: boolean;\n}\n\n/**\n * Abstract base class for qualifier types. Provides default implementations for\n * the {@link QualifierTypes.IQualifierType | IQualifierType} interface.\n * @public\n */\nexport abstract class QualifierType implements IQualifierType {\n  /**\n   * {@inheritdoc QualifierTypes.IQualifierType.name}\n   */\n  public readonly name: QualifierTypeName;\n\n  /**\n   * {@inheritdoc QualifierTypes.IQualifierType.key}\n   */\n  public get key(): QualifierTypeName {\n    return this._collectible.key;\n  }\n\n  /**\n   * {@inheritdoc QualifierTypes.IQualifierType.index}\n   */\n  public get index(): QualifierTypeIndex | undefined {\n    return this._collectible.index;\n  }\n\n  protected readonly _collectible: Collections.Collectible<QualifierTypeName, QualifierTypeIndex>;\n\n  /**\n   * Flag indicating whether this qualifier type allows a list of values in a context.\n   * @public\n   */\n  public readonly allowContextList: boolean;\n\n  /**\n   * Constructor for use by derived classes.\n   * @param name - The name of the qualifier type.\n   * @param allowContextList - Flag indicating whether this qualifier type allows a\n   * comma-separated list of runtime values in the context. Defaults to `false`.\n   */\n  protected constructor({ name, index, allowContextList }: IQualifierTypeCreateParams) {\n    this.name = Convert.qualifierTypeName.convert(name).orThrow();\n    this.allowContextList = allowContextList === true;\n    this._collectible = new Collections.Collectible<QualifierTypeName, QualifierTypeIndex>({\n      key: this.name,\n      index: index,\n      indexConverter: Convert.qualifierTypeIndex\n    });\n  }\n\n  /**\n   * {@inheritdoc QualifierTypes.IQualifierType.isValidConditionValue}\n   */\n  public abstract isValidConditionValue(value: string): value is QualifierConditionValue;\n\n  /**\n   * {@inheritdoc QualifierTypes.IQualifierType.isValidContextValue}\n   */\n  public isValidContextValue(value: string): value is QualifierContextValue {\n    if (this.isValidConditionValue(value)) {\n      return true;\n    }\n    if (this.allowContextList) {\n      return value.split(',').every((v) => this.isValidConditionValue(v.trim()));\n    }\n    return false;\n  }\n\n  /**\n   * {@inheritdoc QualifierTypes.IQualifierType.validateCondition}\n   */\n  public validateCondition(value: string, operator?: ConditionOperator): Result<QualifierConditionValue> {\n    operator = operator ?? 'matches';\n    if (operator !== 'matches') {\n      return fail(`${operator}: invalid condition operator`);\n    } else if (!this.isValidConditionValue(value)) {\n      return fail(`${value}: invalid condition value for qualifierType ${this.name}`);\n    }\n    return succeed(value);\n  }\n\n  /**\n   * {@inheritdoc QualifierTypes.IQualifierType.validateContextValue}\n   */\n  public validateContextValue(value: string): Result<QualifierContextValue> {\n    if (!this.isValidContextValue(value)) {\n      return fail(`${value}: invalid context value for qualifierType ${this.name}`);\n    }\n    return succeed(value);\n  }\n\n  /**\n   * {@inheritdoc QualifierTypes.IQualifierType.matches}\n   */\n  public matches(\n    condition: QualifierConditionValue,\n    context: QualifierContextValue,\n    operator: ConditionOperator\n  ): QualifierMatchScore {\n    if (this.allowContextList) {\n      return this._matchList(condition, QualifierType._splitContext(context), operator);\n    }\n    return this._matchOne(condition, context, operator);\n  }\n\n  /**\n   * {@inheritdoc QualifierTypes.IQualifierType.setIndex}\n   */\n  public setIndex(index: number): Result<QualifierTypeIndex> {\n    return this._collectible.setIndex(index);\n  }\n\n  /**\n   * {@inheritdoc Validate.isValidQualifierTypeName}\n   */\n  public static isValidName(name: string): name is QualifierTypeName {\n    return Validate.isValidQualifierTypeName(name);\n  }\n\n  /**\n   * {@inheritdoc Validate.isValidQualifierTypeIndex}\n   */\n  public static isValidIndex(index: number): index is QualifierTypeIndex {\n    return Validate.isValidQualifierTypeIndex(index);\n  }\n\n  /**\n   * Compares two qualifier types by index.\n   * @param t1 - The first qualifier type to compare.\n   * @param t2 - The second qualifier type to compare.\n   * @returns a number indicating the relative order of the two qualifier types.\n   */\n  public static compare(t1: QualifierType, t2: QualifierType): number {\n    const i1 = t1._collectible.index ?? -1;\n    const i2 = t2._collectible.index ?? -1;\n    let diff = i1 - i2;\n\n    if (diff === 0) {\n      diff = t1.name.localeCompare(t2.name);\n    }\n\n    return diff;\n  }\n\n  /**\n   * Matches a single condition value against a single context value.\n   * @param condition - The {@link QualifierConditionValue | condition value} to match.\n   * @param context - The {@link QualifierContextValue | context value} to match.\n   * @param operator - The {@link ConditionOperator | operator} to use in the match.\n   * @returns a {@link QualifierMatchScore | score} indicating the extent to which the condition\n   * matches the context value.\n   * @public\n   */\n  protected abstract _matchOne(\n    condition: QualifierConditionValue,\n    context: QualifierContextValue,\n    operator: ConditionOperator\n  ): QualifierMatchScore;\n\n  /**\n   * Matches a single condition value against a list of context values.\n   * @param condition - The {@link QualifierConditionValue | condition value} to match.\n   * @param context - The comma-separated list of {@link QualifierContextValue | context values} to match.\n   * @param operator - The {@link ConditionOperator | operator} to use in the match.\n   * @returns a {@link QualifierMatchScore | score} indicating the extent to which the condition\n   * matches the context value.\n   * @public\n   */\n  protected _matchList(\n    condition: QualifierConditionValue,\n    context: QualifierContextValue[],\n    operator: ConditionOperator\n  ): QualifierMatchScore {\n    const scorePerPosition = 1 / context.length;\n    let baseScore = PerfectMatch - scorePerPosition;\n\n    for (let i = 0; i < context.length; i++) {\n      const score = this._matchOne(condition, context[i], operator);\n      if (score > NoMatch) {\n        const adjusted = baseScore + scorePerPosition * score;\n        if (Validate.isValidQualifierMatchScore(adjusted)) {\n          return adjusted;\n        }\n      }\n      baseScore -= scorePerPosition;\n    }\n    return NoMatch;\n  }\n\n  /**\n   * Splits a comma-separated {@link QualifierContextValue | context value} into an array of\n   * individual values.\n   * @param value - The value to split.\n   * @returns an array of individual context values.\n   * @public\n   */\n  protected static _splitContext(value: QualifierContextValue): QualifierContextValue[] {\n    return value.split(',').map((s) => s.trim() as QualifierContextValue);\n  }\n}\n"]}
+{"version":3,"file":"qualifierType.js","sourceRoot":"","sources":["../../../src/packlets/qualifier-types/qualifierType.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 { Collections, ICollectible, Result, fail, succeed } from '@fgv/ts-utils';\nimport {\n  ConditionOperator,\n  Convert,\n  NoMatch,\n  PerfectMatch,\n  QualifierConditionValue,\n  QualifierContextValue,\n  QualifierMatchScore,\n  QualifierTypeIndex,\n  QualifierTypeName,\n  Validate\n} from '../common';\n\n/**\n * Interface for a qualifier type. A qualifier type implements the build and\n * runtime semantics for some class of related qualifiers (e.g. language,\n * territories, etc).\n * @public\n */\nexport interface IQualifierType extends ICollectible<QualifierTypeName, QualifierTypeIndex> {\n  /**\n   * The name of the qualifier type.\n   */\n  readonly name: QualifierTypeName;\n\n  /**\n   * Unique key for this qualifier.\n   */\n  readonly key: QualifierTypeName;\n\n  /**\n   * Global index for this qualifier type. Immutable once set, either at\n   * construction or using {@link QualifierTypes.IQualifierType.setIndex | setIndex}.\n   */\n  readonly index: QualifierTypeIndex | undefined;\n\n  /**\n   * Validates a condition value for this qualifier type.\n   * @param value - The string value to validate.\n   * @returns `Success` with the {@link QualifierConditionValue | validated value}\n   * if the value is valid for use in a condition, `Failure` with error details\n   * otherwise.\n   */\n  isValidConditionValue(value: string): value is QualifierConditionValue;\n\n  /**\n   * Validates a context value for this qualifier type.\n   * @param value - The string value to validate.\n   * @returns `Success` with the {@link QualifierContextValue | validated value}\n   * if the value is valid for use in a runtime context, `Failure` with error\n   * details otherwise.\n   */\n  isValidContextValue(value: string): value is QualifierContextValue;\n\n  /**\n   * Determines if a supplied condition value is a potential match for a possible context value.\n   * @param conditionValue - The condition value.\n   * @param contextValue - The context value.\n   * @returns `true` if the condition value is a potential match for the context value, `false` otherwise.\n   */\n  isPotentialMatch(conditionValue: string, contextValue: string): boolean;\n\n  /**\n   * Validates that a value and optional operator are valid for use in a condition\n   * for qualifiers of this type.\n   * @param value - The string value to validate.\n   * @param operator - An optional operator to validate. Defaults to 'matches'.\n   */\n  validateCondition(value: string, operator?: ConditionOperator): Result<QualifierConditionValue>;\n\n  /**\n   * Validates that a value is valid for use in a runtime context for qualifiers\n   * of this type.\n   * @param value - The string value to validate.\n   * @returns `Success` with the {@link QualifierContextValue | validated value}\n   * if the value is valid for use in a runtime context, `Failure` with error\n   * details otherwise.\n   */\n  validateContextValue(value: string): Result<QualifierContextValue>;\n\n  /**\n   * Determines the extent to which a condition matches a context value for this\n   * qualifier type.\n   * @param condition - The condition value to evaluate.\n   * @param context - The context value to evaluate.\n   * @param operator - The operator to use in evaluating the match.\n   * @returns a {@link QualifierMatchScore | score} indicating the extent to which\n   * the condition matches the context value.\n   */\n  matches(\n    condition: QualifierConditionValue,\n    context: QualifierContextValue,\n    operator: ConditionOperator\n  ): QualifierMatchScore;\n\n  /**\n   * Sets the index for this qualifier type. Once set, index is immutable.\n   */\n  setIndex(index: number): Result<QualifierTypeIndex>;\n}\n\n/**\n * Parameters used to create a base {@link QualifierTypes.QualifierType | qualifier type}.\n * @public\n */\nexport interface IQualifierTypeCreateParams {\n  /**\n   * The name of the qualifier type. No default value.\n   */\n  name: string;\n\n  /**\n   * Global index for this qualifier type.\n   */\n  index?: number;\n\n  /**\n   * Flag indicating whether this qualifier type allows a list of values in a context.\n   * Defaults to `false`.\n   */\n  allowContextList?: boolean;\n}\n\n/**\n * Abstract base class for qualifier types. Provides default implementations for\n * the {@link QualifierTypes.IQualifierType | IQualifierType} interface.\n * @public\n */\nexport abstract class QualifierType implements IQualifierType {\n  /**\n   * {@inheritdoc QualifierTypes.IQualifierType.name}\n   */\n  public readonly name: QualifierTypeName;\n\n  /**\n   * {@inheritdoc QualifierTypes.IQualifierType.key}\n   */\n  public get key(): QualifierTypeName {\n    return this._collectible.key;\n  }\n\n  /**\n   * {@inheritdoc QualifierTypes.IQualifierType.index}\n   */\n  public get index(): QualifierTypeIndex | undefined {\n    return this._collectible.index;\n  }\n\n  protected readonly _collectible: Collections.Collectible<QualifierTypeName, QualifierTypeIndex>;\n\n  /**\n   * Flag indicating whether this qualifier type allows a list of values in a context.\n   * @public\n   */\n  public readonly allowContextList: boolean;\n\n  /**\n   * Constructor for use by derived classes.\n   * @param name - The name of the qualifier type.\n   * @param allowContextList - Flag indicating whether this qualifier type allows a\n   * comma-separated list of runtime values in the context. Defaults to `false`.\n   */\n  protected constructor({ name, index, allowContextList }: IQualifierTypeCreateParams) {\n    this.name = Convert.qualifierTypeName.convert(name).orThrow();\n    this.allowContextList = allowContextList === true;\n    this._collectible = new Collections.Collectible<QualifierTypeName, QualifierTypeIndex>({\n      key: this.name,\n      index: index,\n      indexConverter: Convert.qualifierTypeIndex\n    });\n  }\n\n  /**\n   * {@inheritdoc QualifierTypes.IQualifierType.isValidConditionValue}\n   */\n  public abstract isValidConditionValue(value: string): value is QualifierConditionValue;\n\n  /**\n   * {@inheritdoc QualifierTypes.IQualifierType.isValidContextValue}\n   */\n  public isValidContextValue(value: string): value is QualifierContextValue {\n    if (this.isValidConditionValue(value)) {\n      return true;\n    }\n    if (this.allowContextList) {\n      /* c8 ignore next 1 - functional code tested but coverage intermittently missed */\n      return value.split(',').every((v) => this.isValidConditionValue(v.trim()));\n    }\n    /* c8 ignore next 1 - functional code tested but coverage intermittently missed */\n    return false;\n  }\n\n  /**\n   * {@inheritdoc QualifierTypes.IQualifierType.isPotentialMatch}\n   */\n  public isPotentialMatch(conditionValue: string, contextValue: string): boolean {\n    if (this.isValidConditionValue(conditionValue) && this.isValidContextValue(contextValue)) {\n      return this._matchOne(conditionValue, contextValue, 'matches') !== NoMatch;\n    }\n    return false;\n  }\n\n  /**\n   * {@inheritdoc QualifierTypes.IQualifierType.validateCondition}\n   */\n  public validateCondition(value: string, operator?: ConditionOperator): Result<QualifierConditionValue> {\n    operator = operator ?? 'matches';\n    /* c8 ignore next 2 - functional error case tested but coverage intermittently missed */\n    if (operator !== 'matches') {\n      return fail(`${operator}: invalid condition operator`);\n      /* c8 ignore next 2 - functional error case tested but coverage intermittently missed */\n    } else if (!this.isValidConditionValue(value)) {\n      return fail(`${value}: invalid condition value for qualifierType ${this.name}`);\n    }\n    return succeed(value);\n  }\n\n  /**\n   * {@inheritdoc QualifierTypes.IQualifierType.validateContextValue}\n   */\n  public validateContextValue(value: string): Result<QualifierContextValue> {\n    /* c8 ignore next 2 - functional error case tested but coverage intermittently missed */\n    if (!this.isValidContextValue(value)) {\n      return fail(`${value}: invalid context value for qualifierType ${this.name}`);\n    }\n    return succeed(value);\n  }\n\n  /**\n   * {@inheritdoc QualifierTypes.IQualifierType.matches}\n   */\n  public matches(\n    condition: QualifierConditionValue,\n    context: QualifierContextValue,\n    operator: ConditionOperator\n  ): QualifierMatchScore {\n    if (this.allowContextList) {\n      return this._matchList(condition, QualifierType._splitContext(context), operator);\n    }\n    return this._matchOne(condition, context, operator);\n  }\n\n  /**\n   * {@inheritdoc QualifierTypes.IQualifierType.setIndex}\n   */\n  public setIndex(index: number): Result<QualifierTypeIndex> {\n    return this._collectible.setIndex(index);\n  }\n\n  /**\n   * {@inheritdoc Validate.isValidQualifierTypeName}\n   */\n  public static isValidName(name: string): name is QualifierTypeName {\n    return Validate.isValidQualifierTypeName(name);\n  }\n\n  /**\n   * {@inheritdoc Validate.isValidQualifierTypeIndex}\n   */\n  public static isValidIndex(index: number): index is QualifierTypeIndex {\n    return Validate.isValidQualifierTypeIndex(index);\n  }\n\n  /**\n   * Compares two qualifier types by index.\n   * @param t1 - The first qualifier type to compare.\n   * @param t2 - The second qualifier type to compare.\n   * @returns a number indicating the relative order of the two qualifier types.\n   */\n  public static compare(t1: QualifierType, t2: QualifierType): number {\n    const i1 = t1._collectible.index ?? -1;\n    const i2 = t2._collectible.index ?? -1;\n    let diff = i1 - i2;\n\n    if (diff === 0) {\n      diff = t1.name.localeCompare(t2.name);\n    }\n\n    return diff;\n  }\n\n  /**\n   * Matches a single condition value against a single context value.\n   * @param condition - The {@link QualifierConditionValue | condition value} to match.\n   * @param context - The {@link QualifierContextValue | context value} to match.\n   * @param operator - The {@link ConditionOperator | operator} to use in the match.\n   * @returns a {@link QualifierMatchScore | score} indicating the extent to which\n   * the condition matches the context value.\n   * @public\n   */\n  protected abstract _matchOne(\n    condition: QualifierConditionValue,\n    context: QualifierContextValue,\n    operator: ConditionOperator\n  ): QualifierMatchScore;\n\n  /**\n   * Matches a single condition value against a list of context values.\n   * @param condition - The {@link QualifierConditionValue | condition value} to match.\n   * @param context - The comma-separated list of {@link QualifierContextValue | context values} to match.\n   * @param operator - The {@link ConditionOperator | operator} to use in the match.\n   * @returns a {@link QualifierMatchScore | score} indicating the extent to which\n   * the condition matches the context value.\n   * @public\n   */\n  protected _matchList(\n    condition: QualifierConditionValue,\n    context: QualifierContextValue[],\n    operator: ConditionOperator\n  ): QualifierMatchScore {\n    const scorePerPosition = 1 / context.length;\n    let baseScore = PerfectMatch - scorePerPosition;\n\n    for (let i = 0; i < context.length; i++) {\n      const score = this._matchOne(condition, context[i], operator);\n      if (score > NoMatch) {\n        const adjusted = baseScore + scorePerPosition * score;\n        if (Validate.isValidQualifierMatchScore(adjusted)) {\n          return adjusted;\n        }\n      }\n      baseScore -= scorePerPosition;\n    }\n    return NoMatch;\n  }\n\n  /**\n   * Splits a comma-separated {@link QualifierContextValue | context value} into an\n   * array of individual values.\n   * @param value - The value to split.\n   * @returns an array of individual context values.\n   * @public\n   */\n  protected static _splitContext(value: QualifierContextValue): QualifierContextValue[] {\n    return value.split(',').map((s) => s.trim() as QualifierContextValue);\n  }\n}\n"]}

package/lib/packlets/qualifier-types/qualifierTypeCollector.d.ts

@@ -19,7 +19,8 @@ export interface IQualifierTypeCollectorCreateParams {
 export declare class QualifierTypeCollector extends ValidatingConvertingCollector<QualifierType, QualifierType> {
     /**
      * Constructor for a {@link QualifierTypes.QualifierTypeCollector | QualifierTypeCollector} object.
-     * @param params - Optional {@link QualifierTypes.IQualifierTypeCollectorCreateParams | parameters} used to construct the collector.
+     * @param params - Optional {@link QualifierTypes.IQualifierTypeCollectorCreateParams | parameters}
+     * used to construct the collector.
      */
     protected constructor({ qualifierTypes }: IQualifierTypeCollectorCreateParams);
     /**
@@ -33,7 +34,8 @@ export declare class QualifierTypeCollector extends ValidatingConvertingCollecto
     protected static _toQualifierType(from: unknown): Result<QualifierType>;
 }
 /**
- * Interface exposing non-mutating members of a {@link QualifierTypes.QualifierTypeCollector | QualifierTypeCollector}.
+ * Interface exposing non-mutating members of a
+ * {@link QualifierTypes.QualifierTypeCollector | QualifierTypeCollector}.
  * @public
  */
 export type ReadOnlyQualifierTypeCollector = Collections.IReadOnlyValidatingCollector<QualifierType>;

package/lib/packlets/qualifier-types/qualifierTypeCollector.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"qualifierTypeCollector.d.ts","sourceRoot":"","sources":["../../../src/packlets/qualifier-types/qualifierTypeCollector.ts"],"names":[],"mappings":"AAuBA,OAAO,EACL,WAAW,EACX,MAAM,EACN,6BAA6B,EAI9B,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,OAAO,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAE9C;;;GAGG;AACH,MAAM,WAAW,mCAAmC;IAClD;;;OAGG;IACH,cAAc,CAAC,EAAE,aAAa,EAAE,CAAC;CAClC;AAED;;;GAGG;AACH,qBAAa,sBAAuB,SAAQ,6BAA6B,CAAC,aAAa,EAAE,aAAa,CAAC;IACrG;;;OAGG;IACH,SAAS,aAAa,EAAE,cAAc,EAAE,EAAE,mCAAmC;IAe7E;;;;;OAKG;WACW,MAAM,CAAC,MAAM,CAAC,EAAE,mCAAmC,GAAG,MAAM,CAAC,sBAAsB,CAAC;IAMlG,SAAS,CAAC,MAAM,CAAC,qBAAqB,CACpC,GAAG,EAAE,iBAAiB,EACtB,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,aAAa,GACnB,MAAM,CAAC,aAAa,CAAC;IAIxB,SAAS,CAAC,MAAM,CAAC,gBAAgB,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,CAAC,aAAa,CAAC;CAGxE;AAED;;;GAGG;AACH,MAAM,MAAM,8BAA8B,GAAG,WAAW,CAAC,4BAA4B,CAAC,aAAa,CAAC,CAAC"}
+{"version":3,"file":"qualifierTypeCollector.d.ts","sourceRoot":"","sources":["../../../src/packlets/qualifier-types/qualifierTypeCollector.ts"],"names":[],"mappings":"AAuBA,OAAO,EACL,WAAW,EACX,MAAM,EACN,6BAA6B,EAI9B,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,OAAO,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAE9C;;;GAGG;AACH,MAAM,WAAW,mCAAmC;IAClD;;;OAGG;IACH,cAAc,CAAC,EAAE,aAAa,EAAE,CAAC;CAClC;AAED;;;GAGG;AACH,qBAAa,sBAAuB,SAAQ,6BAA6B,CAAC,aAAa,EAAE,aAAa,CAAC;IACrG;;;;OAIG;IACH,SAAS,aAAa,EAAE,cAAc,EAAE,EAAE,mCAAmC;IAe7E;;;;;OAKG;WACW,MAAM,CAAC,MAAM,CAAC,EAAE,mCAAmC,GAAG,MAAM,CAAC,sBAAsB,CAAC;IAMlG,SAAS,CAAC,MAAM,CAAC,qBAAqB,CACpC,GAAG,EAAE,iBAAiB,EACtB,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,aAAa,GACnB,MAAM,CAAC,aAAa,CAAC;IAIxB,SAAS,CAAC,MAAM,CAAC,gBAAgB,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,CAAC,aAAa,CAAC;CAGxE;AAED;;;;GAIG;AACH,MAAM,MAAM,8BAA8B,GAAG,WAAW,CAAC,4BAA4B,CAAC,aAAa,CAAC,CAAC"}

package/lib/packlets/qualifier-types/qualifierTypeCollector.js

@@ -65,7 +65,8 @@ const qualifierType_1 = require("./qualifierType");
 class QualifierTypeCollector extends ts_utils_1.ValidatingConvertingCollector {
     /**
      * Constructor for a {@link QualifierTypes.QualifierTypeCollector | QualifierTypeCollector} object.
-     * @param params - Optional {@link QualifierTypes.IQualifierTypeCollectorCreateParams | parameters} used to construct the collector.
+     * @param params - Optional {@link QualifierTypes.IQualifierTypeCollectorCreateParams | parameters}
+     * used to construct the collector.
      */
     constructor({ qualifierTypes }) {
         super({

package/lib/packlets/qualifier-types/qualifierTypeCollector.js.map

@@ -1 +1 @@
-{"version":3,"file":"qualifierTypeCollector.js","sourceRoot":"","sources":["../../../src/packlets/qualifier-types/qualifierTypeCollector.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAEH,kDAAoC;AACpC,4CAOuB;AACvB,mDAAgD;AAehD;;;GAGG;AACH,MAAa,sBAAuB,SAAQ,wCAA2D;IACrG;;;OAGG;IACH,YAAsB,EAAE,cAAc,EAAuC;QAC3E,KAAK,CAAC;YACJ,UAAU,EAAE,IAAI,sBAAW,CAAC,kBAAkB,CAAC;gBAC7C,GAAG,EAAE,MAAM,CAAC,OAAO,CAAC,iBAAiB;gBACrC,KAAK,EAAE,sBAAsB,CAAC,gBAAgB;aAC/C,CAAC;YACF,OAAO,EAAE,sBAAsB,CAAC,qBAAqB;SACtD,CAAC,CAAC;QAEH,yEAAyE;QACzE,cAAc,aAAd,cAAc,uBAAd,cAAc,CAAE,OAAO,CAAC,CAAC,EAAE,EAAE,EAAE;YAC7B,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC;QACzB,CAAC,CAAC,CAAC;IACL,CAAC;IAED;;;;;OAKG;IACI,MAAM,CAAC,MAAM,CAAC,MAA4C;QAC/D,yEAAyE;QACzE,MAAM,GAAG,MAAM,aAAN,MAAM,cAAN,MAAM,GAAI,EAAE,CAAC;QACtB,OAAO,IAAA,wBAAa,EAAC,GAAG,EAAE,CAAC,IAAI,sBAAsB,CAAC,MAAM,CAAC,CAAC,CAAC;IACjE,CAAC;IAES,MAAM,CAAC,qBAAqB,CACpC,GAAsB,EACtB,KAAa,EACb,KAAoB;QAEpB,OAAO,IAAA,kBAAO,EAAC,KAAK,CAAC,CAAC;IACxB,CAAC;IAES,MAAM,CAAC,gBAAgB,CAAC,IAAa;QAC7C,OAAO,IAAI,YAAY,6BAAa,CAAC,CAAC,CAAC,IAAA,kBAAO,EAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAA,eAAI,EAAC,qBAAqB,CAAC,CAAC;IACrF,CAAC;CACF;AA3CD,wDA2CC","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 * as Common from '../common';\nimport {\n  Collections,\n  Result,\n  ValidatingConvertingCollector,\n  captureResult,\n  fail,\n  succeed\n} from '@fgv/ts-utils';\nimport { QualifierType } from './qualifierType';\nimport { QualifierTypeName } from '../common';\n\n/**\n * Parameters for creating a new {@link QualifierTypes.QualifierTypeCollector | QualifierTypeCollector}.\n * @public\n */\nexport interface IQualifierTypeCollectorCreateParams {\n  /**\n   * Optional list of {@link QualifierTypes.QualifierType | QualifierTypes} to add to the collector\n   * on creation.\n   */\n  qualifierTypes?: QualifierType[];\n}\n\n/**\n * Collector for {@link QualifierTypes.QualifierType | QualifierType} objects.\n * @public\n */\nexport class QualifierTypeCollector extends ValidatingConvertingCollector<QualifierType, QualifierType> {\n  /**\n   * Constructor for a {@link QualifierTypes.QualifierTypeCollector | QualifierTypeCollector} object.\n   * @param params - Optional {@link QualifierTypes.IQualifierTypeCollectorCreateParams | parameters} used to construct the collector.\n   */\n  protected constructor({ qualifierTypes }: IQualifierTypeCollectorCreateParams) {\n    super({\n      converters: new Collections.KeyValueConverters({\n        key: Common.Convert.qualifierTypeName,\n        value: QualifierTypeCollector._toQualifierType\n      }),\n      factory: QualifierTypeCollector._qualifierTypeFactory\n    });\n\n    /* c8 ignore next 1 - coverage seems to intermittently miss the branch */\n    qualifierTypes?.forEach((qt) => {\n      this.add(qt).orThrow();\n    });\n  }\n\n  /**\n   * Creates a new {@link QualifierTypes.QualifierTypeCollector | QualifierTypeCollector} object.\n   * @param params - Optional {@link QualifierTypes.IQualifierTypeCollectorCreateParams | parameters}\n   * used to create the collector.\n   * @returns `Success` with the new collector if successful, or `Failure` if not.\n   */\n  public static create(params?: IQualifierTypeCollectorCreateParams): Result<QualifierTypeCollector> {\n    /* c8 ignore next 1 - coverage seems to miss the branch intermittently */\n    params = params ?? {};\n    return captureResult(() => new QualifierTypeCollector(params));\n  }\n\n  protected static _qualifierTypeFactory(\n    key: QualifierTypeName,\n    index: number,\n    value: QualifierType\n  ): Result<QualifierType> {\n    return succeed(value);\n  }\n\n  protected static _toQualifierType(from: unknown): Result<QualifierType> {\n    return from instanceof QualifierType ? succeed(from) : fail('not a QualifierType');\n  }\n}\n\n/**\n * Interface exposing non-mutating members of a {@link QualifierTypes.QualifierTypeCollector | QualifierTypeCollector}.\n * @public\n */\nexport type ReadOnlyQualifierTypeCollector = Collections.IReadOnlyValidatingCollector<QualifierType>;\n"]}
+{"version":3,"file":"qualifierTypeCollector.js","sourceRoot":"","sources":["../../../src/packlets/qualifier-types/qualifierTypeCollector.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAEH,kDAAoC;AACpC,4CAOuB;AACvB,mDAAgD;AAehD;;;GAGG;AACH,MAAa,sBAAuB,SAAQ,wCAA2D;IACrG;;;;OAIG;IACH,YAAsB,EAAE,cAAc,EAAuC;QAC3E,KAAK,CAAC;YACJ,UAAU,EAAE,IAAI,sBAAW,CAAC,kBAAkB,CAAC;gBAC7C,GAAG,EAAE,MAAM,CAAC,OAAO,CAAC,iBAAiB;gBACrC,KAAK,EAAE,sBAAsB,CAAC,gBAAgB;aAC/C,CAAC;YACF,OAAO,EAAE,sBAAsB,CAAC,qBAAqB;SACtD,CAAC,CAAC;QAEH,yEAAyE;QACzE,cAAc,aAAd,cAAc,uBAAd,cAAc,CAAE,OAAO,CAAC,CAAC,EAAE,EAAE,EAAE;YAC7B,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC;QACzB,CAAC,CAAC,CAAC;IACL,CAAC;IAED;;;;;OAKG;IACI,MAAM,CAAC,MAAM,CAAC,MAA4C;QAC/D,yEAAyE;QACzE,MAAM,GAAG,MAAM,aAAN,MAAM,cAAN,MAAM,GAAI,EAAE,CAAC;QACtB,OAAO,IAAA,wBAAa,EAAC,GAAG,EAAE,CAAC,IAAI,sBAAsB,CAAC,MAAM,CAAC,CAAC,CAAC;IACjE,CAAC;IAES,MAAM,CAAC,qBAAqB,CACpC,GAAsB,EACtB,KAAa,EACb,KAAoB;QAEpB,OAAO,IAAA,kBAAO,EAAC,KAAK,CAAC,CAAC;IACxB,CAAC;IAES,MAAM,CAAC,gBAAgB,CAAC,IAAa;QAC7C,OAAO,IAAI,YAAY,6BAAa,CAAC,CAAC,CAAC,IAAA,kBAAO,EAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAA,eAAI,EAAC,qBAAqB,CAAC,CAAC;IACrF,CAAC;CACF;AA5CD,wDA4CC","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 * as Common from '../common';\nimport {\n  Collections,\n  Result,\n  ValidatingConvertingCollector,\n  captureResult,\n  fail,\n  succeed\n} from '@fgv/ts-utils';\nimport { QualifierType } from './qualifierType';\nimport { QualifierTypeName } from '../common';\n\n/**\n * Parameters for creating a new {@link QualifierTypes.QualifierTypeCollector | QualifierTypeCollector}.\n * @public\n */\nexport interface IQualifierTypeCollectorCreateParams {\n  /**\n   * Optional list of {@link QualifierTypes.QualifierType | QualifierTypes} to add to the collector\n   * on creation.\n   */\n  qualifierTypes?: QualifierType[];\n}\n\n/**\n * Collector for {@link QualifierTypes.QualifierType | QualifierType} objects.\n * @public\n */\nexport class QualifierTypeCollector extends ValidatingConvertingCollector<QualifierType, QualifierType> {\n  /**\n   * Constructor for a {@link QualifierTypes.QualifierTypeCollector | QualifierTypeCollector} object.\n   * @param params - Optional {@link QualifierTypes.IQualifierTypeCollectorCreateParams | parameters}\n   * used to construct the collector.\n   */\n  protected constructor({ qualifierTypes }: IQualifierTypeCollectorCreateParams) {\n    super({\n      converters: new Collections.KeyValueConverters({\n        key: Common.Convert.qualifierTypeName,\n        value: QualifierTypeCollector._toQualifierType\n      }),\n      factory: QualifierTypeCollector._qualifierTypeFactory\n    });\n\n    /* c8 ignore next 1 - coverage seems to intermittently miss the branch */\n    qualifierTypes?.forEach((qt) => {\n      this.add(qt).orThrow();\n    });\n  }\n\n  /**\n   * Creates a new {@link QualifierTypes.QualifierTypeCollector | QualifierTypeCollector} object.\n   * @param params - Optional {@link QualifierTypes.IQualifierTypeCollectorCreateParams | parameters}\n   * used to create the collector.\n   * @returns `Success` with the new collector if successful, or `Failure` if not.\n   */\n  public static create(params?: IQualifierTypeCollectorCreateParams): Result<QualifierTypeCollector> {\n    /* c8 ignore next 1 - coverage seems to miss the branch intermittently */\n    params = params ?? {};\n    return captureResult(() => new QualifierTypeCollector(params));\n  }\n\n  protected static _qualifierTypeFactory(\n    key: QualifierTypeName,\n    index: number,\n    value: QualifierType\n  ): Result<QualifierType> {\n    return succeed(value);\n  }\n\n  protected static _toQualifierType(from: unknown): Result<QualifierType> {\n    return from instanceof QualifierType ? succeed(from) : fail('not a QualifierType');\n  }\n}\n\n/**\n * Interface exposing non-mutating members of a\n * {@link QualifierTypes.QualifierTypeCollector | QualifierTypeCollector}.\n * @public\n */\nexport type ReadOnlyQualifierTypeCollector = Collections.IReadOnlyValidatingCollector<QualifierType>;\n"]}