@fgv/ts-res 4.5.0-0

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

@@ -0,0 +1,114 @@
+"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.LiteralQualifierType = void 0;
+const ts_utils_1 = require("@fgv/ts-utils");
+const common_1 = require("../common");
+const qualifierType_1 = require("./qualifierType");
+/**
+ * A {@link QualifierTypes.QualifierType | qualifier} that matches a literal value., optionally case-sensitive
+ * or matching against an ordered list of values at runtime.
+ * @public
+ */
+class LiteralQualifierType extends qualifierType_1.QualifierType {
+    /**
+     * Constructs a new {@link QualifierTypes.LiteralQualifierType | LiteralQualifierType}.
+     * @param name - Optional name for the qualifier type. Defaults to 'literal'.
+     * @param caseSensitive - Optional flag indicating whether the match should be case-sensitive. Defaults to false.
+     * @param allowContextList - Optional flag indicating whether the context can be a list of values. Defaults to false.
+     * @public
+     */
+    constructor({ name, caseSensitive, allowContextList, enumeratedValues, index }) {
+        allowContextList = allowContextList !== false;
+        super({
+            name: name !== null && name !== void 0 ? name : 'literal',
+            allowContextList,
+            index: index !== undefined ? common_1.Convert.qualifierTypeIndex.convert(index).orThrow() : undefined
+        });
+        this.caseSensitive = caseSensitive === true;
+        this.enumeratedValues = enumeratedValues
+            ? (0, ts_utils_1.mapResults)(Array.from(enumeratedValues).map(LiteralQualifierType.toLiteralConditionValue)).orThrow()
+            : undefined;
+    }
+    /**
+     * Determines whether a value is a valid condition value for a literal qualifier. The
+     * {@link QualifierTypes.LiteralQualifierType | LiteralQualifierType} accepts
+     * any identifier as a valid condition value.
+     * @param value - The value to validate.
+     * @returns `true` if the value is a valid condition value, `false` otherwise.
+     */
+    isValidConditionValue(value) {
+        if (this.enumeratedValues) {
+            if (this.caseSensitive) {
+                return this.enumeratedValues.includes(value);
+            }
+            return this.enumeratedValues.some((v) => v.toLowerCase() === value.toLowerCase());
+        }
+        return LiteralQualifierType.isValidLiteralConditionValue(value);
+    }
+    /**
+     * {@inheritdoc QualifierTypes.QualifierType._matchOne}
+     */
+    _matchOne(condition, context, operator) {
+        if (this.caseSensitive) {
+            return condition === context ? common_1.PerfectMatch : common_1.NoMatch;
+        }
+        else {
+            return condition.toLowerCase() === context.toLowerCase() ? common_1.PerfectMatch : common_1.NoMatch;
+        }
+    }
+    /**
+     * Creates a new {@link QualifierTypes.LiteralQualifierType | LiteralQualifierType}.
+     * @param params - Optional {@link QualifierTypes.ILiteralQualifierTypeCreateParams | parameters}
+     * to use when creating the new instance.
+     * @returns `Success` with the new {@link QualifierTypes.LiteralQualifierType | LiteralQualifierType}
+     * if successful, `Failure` with an error message otherwise.
+     * @public
+     */
+    static create(params) {
+        return (0, ts_utils_1.captureResult)(() => new LiteralQualifierType(params !== null && params !== void 0 ? params : {}));
+    }
+    /**
+     * Checks if the given value is a valid literal condition value.
+     * @param from - The value to validate.
+     * @returns `true` if the value is a valid literal condition value, otherwise `false`.
+     * @public
+     */
+    static isValidLiteralConditionValue(from) {
+        return common_1.Validate.RegularExpressions.identifier.test(from);
+    }
+    /**
+     * Converts a string to a {@link QualifierConditionValue | literal condition value}.
+     * @param from - The string to convert.
+     * @returns `Success` with the converted value if valid, or `Failure` with an error message
+     * if not.
+     * @public
+     */
+    static toLiteralConditionValue(from) {
+        return LiteralQualifierType.isValidLiteralConditionValue(from)
+            ? (0, ts_utils_1.succeed)(from)
+            : (0, ts_utils_1.fail)(`${from}: not a valid literal condition value.`);
+    }
+}
+exports.LiteralQualifierType = LiteralQualifierType;
+//# sourceMappingURL=literalQualifierType.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"literalQualifierType.js","sourceRoot":"","sources":["../../../src/packlets/qualifier-types/literalQualifierType.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;;;AAEH,4CAAiF;AACjF,sCASmB;AACnB,mDAAgD;AAoChD;;;;GAIG;AACH,MAAa,oBAAqB,SAAQ,6BAAa;IAWrD;;;;;;OAMG;IACH,YAAsB,EACpB,IAAI,EACJ,aAAa,EACb,gBAAgB,EAChB,gBAAgB,EAChB,KAAK,EAC6B;QAClC,gBAAgB,GAAG,gBAAgB,KAAK,KAAK,CAAC;QAC9C,KAAK,CAAC;YACJ,IAAI,EAAE,IAAI,aAAJ,IAAI,cAAJ,IAAI,GAAI,SAAS;YACvB,gBAAgB;YAChB,KAAK,EAAE,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,gBAAO,CAAC,kBAAkB,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,SAAS;SAC7F,CAAC,CAAC;QACH,IAAI,CAAC,aAAa,GAAG,aAAa,KAAK,IAAI,CAAC;QAC5C,IAAI,CAAC,gBAAgB,GAAG,gBAAgB;YACtC,CAAC,CAAC,IAAA,qBAAU,EAAC,KAAK,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC,GAAG,CAAC,oBAAoB,CAAC,uBAAuB,CAAC,CAAC,CAAC,OAAO,EAAE;YACtG,CAAC,CAAC,SAAS,CAAC;IAChB,CAAC;IAED;;;;;;OAMG;IACI,qBAAqB,CAAC,KAAa;QACxC,IAAI,IAAI,CAAC,gBAAgB,EAAE,CAAC;YAC1B,IAAI,IAAI,CAAC,aAAa,EAAE,CAAC;gBACvB,OAAO,IAAI,CAAC,gBAAgB,CAAC,QAAQ,CAAC,KAAgC,CAAC,CAAC;YAC1E,CAAC;YACD,OAAO,IAAI,CAAC,gBAAgB,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,EAAE,KAAK,KAAK,CAAC,WAAW,EAAE,CAAC,CAAC;QACpF,CAAC;QACD,OAAO,oBAAoB,CAAC,4BAA4B,CAAC,KAAK,CAAC,CAAC;IAClE,CAAC;IAED;;OAEG;IACO,SAAS,CACjB,SAAkC,EAClC,OAA8B,EAC9B,QAA2B;QAE3B,IAAI,IAAI,CAAC,aAAa,EAAE,CAAC;YACvB,OAAO,SAAS,KAAM,OAAkB,CAAC,CAAC,CAAC,qBAAY,CAAC,CAAC,CAAC,gBAAO,CAAC;QACpE,CAAC;aAAM,CAAC;YACN,OAAO,SAAS,CAAC,WAAW,EAAE,KAAK,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,qBAAY,CAAC,CAAC,CAAC,gBAAO,CAAC;QACpF,CAAC;IACH,CAAC;IAED;;;;;;;OAOG;IACI,MAAM,CAAC,MAAM,CAAC,MAA0C;QAC7D,OAAO,IAAA,wBAAa,EAAC,GAAG,EAAE,CAAC,IAAI,oBAAoB,CAAC,MAAM,aAAN,MAAM,cAAN,MAAM,GAAI,EAAE,CAAC,CAAC,CAAC;IACrE,CAAC;IAED;;;;;OAKG;IACI,MAAM,CAAC,4BAA4B,CAAC,IAAY;QACrD,OAAO,iBAAQ,CAAC,kBAAkB,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC3D,CAAC;IAED;;;;;;OAMG;IACI,MAAM,CAAC,uBAAuB,CAAC,IAAY;QAChD,OAAO,oBAAoB,CAAC,4BAA4B,CAAC,IAAI,CAAC;YAC5D,CAAC,CAAC,IAAA,kBAAO,EAAC,IAAI,CAAC;YACf,CAAC,CAAC,IAAA,eAAI,EAAC,GAAG,IAAI,wCAAwC,CAAC,CAAC;IAC5D,CAAC;CACF;AAvGD,oDAuGC","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, mapResults, Result, fail, succeed } from '@fgv/ts-utils';\nimport {\n  ConditionOperator,\n  Convert,\n  NoMatch,\n  PerfectMatch,\n  QualifierConditionValue,\n  QualifierContextValue,\n  QualifierMatchScore,\n  Validate\n} from '../common';\nimport { QualifierType } from './qualifierType';\n\n/**\n * Interface defining the parameters that can be used to create a new\n * {@link QualifierTypes.LiteralQualifierType | LiteralQualifierType}.\n * @public\n */\nexport interface ILiteralQualifierTypeCreateParams {\n  /**\n   * Optional name for the qualifier type. Defaults to 'literal'.\n   */\n  name?: string;\n\n  /**\n   * Optional flag indicating whether the context can be a list of values.\n   * Defaults to `true`.\n   */\n  allowContextList?: boolean;\n\n  /**\n   * Optional flag indicating whether the match should be case-sensitive. Defaults to false.\n   */\n  caseSensitive?: boolean;\n\n  /**\n   * Optional array of enumerated values to further constrain the type. Defaults to no\n   * constraint.\n   */\n  enumeratedValues?: ReadonlyArray<string>;\n\n  /**\n   * Global index for this qualifier type.\n   */\n  index?: number;\n}\n\n/**\n * A {@link QualifierTypes.QualifierType | qualifier} that matches a literal value., optionally case-sensitive\n * or matching against an ordered list of values at runtime.\n * @public\n */\nexport class LiteralQualifierType extends QualifierType {\n  /**\n   * Indicates whether the qualifier match is case-sensitive.\n   */\n  public readonly caseSensitive: boolean;\n\n  /**\n   * Optional array of enumerated values to further constrain the type.\n   */\n  public readonly enumeratedValues?: ReadonlyArray<QualifierConditionValue>;\n\n  /**\n   * Constructs a new {@link QualifierTypes.LiteralQualifierType | LiteralQualifierType}.\n   * @param name - Optional name for the qualifier type. Defaults to 'literal'.\n   * @param caseSensitive - Optional flag indicating whether the match should be case-sensitive. Defaults to false.\n   * @param allowContextList - Optional flag indicating whether the context can be a list of values. Defaults to false.\n   * @public\n   */\n  protected constructor({\n    name,\n    caseSensitive,\n    allowContextList,\n    enumeratedValues,\n    index\n  }: ILiteralQualifierTypeCreateParams) {\n    allowContextList = allowContextList !== false;\n    super({\n      name: name ?? 'literal',\n      allowContextList,\n      index: index !== undefined ? Convert.qualifierTypeIndex.convert(index).orThrow() : undefined\n    });\n    this.caseSensitive = caseSensitive === true;\n    this.enumeratedValues = enumeratedValues\n      ? mapResults(Array.from(enumeratedValues).map(LiteralQualifierType.toLiteralConditionValue)).orThrow()\n      : undefined;\n  }\n\n  /**\n   * Determines whether a value is a valid condition value for a literal qualifier. The\n   * {@link QualifierTypes.LiteralQualifierType | LiteralQualifierType} accepts\n   * any identifier as a valid condition value.\n   * @param value - The value to validate.\n   * @returns `true` if the value is a valid condition value, `false` otherwise.\n   */\n  public isValidConditionValue(value: string): value is QualifierConditionValue {\n    if (this.enumeratedValues) {\n      if (this.caseSensitive) {\n        return this.enumeratedValues.includes(value as QualifierConditionValue);\n      }\n      return this.enumeratedValues.some((v) => v.toLowerCase() === value.toLowerCase());\n    }\n    return LiteralQualifierType.isValidLiteralConditionValue(value);\n  }\n\n  /**\n   * {@inheritdoc QualifierTypes.QualifierType._matchOne}\n   */\n  protected _matchOne(\n    condition: QualifierConditionValue,\n    context: QualifierContextValue,\n    operator: ConditionOperator\n  ): QualifierMatchScore {\n    if (this.caseSensitive) {\n      return condition === (context as string) ? PerfectMatch : NoMatch;\n    } else {\n      return condition.toLowerCase() === context.toLowerCase() ? PerfectMatch : NoMatch;\n    }\n  }\n\n  /**\n   * Creates a new {@link QualifierTypes.LiteralQualifierType | LiteralQualifierType}.\n   * @param params - Optional {@link QualifierTypes.ILiteralQualifierTypeCreateParams | parameters}\n   * to use when creating the new instance.\n   * @returns `Success` with the new {@link QualifierTypes.LiteralQualifierType | LiteralQualifierType}\n   * if successful, `Failure` with an error message otherwise.\n   * @public\n   */\n  public static create(params?: ILiteralQualifierTypeCreateParams): Result<LiteralQualifierType> {\n    return captureResult(() => new LiteralQualifierType(params ?? {}));\n  }\n\n  /**\n   * Checks if the given value is a valid literal condition value.\n   * @param from - The value to validate.\n   * @returns `true` if the value is a valid literal condition value, otherwise `false`.\n   * @public\n   */\n  public static isValidLiteralConditionValue(from: string): from is QualifierConditionValue {\n    return Validate.RegularExpressions.identifier.test(from);\n  }\n\n  /**\n   * Converts a string to a {@link QualifierConditionValue | literal condition value}.\n   * @param from - The string to convert.\n   * @returns `Success` with the converted value if valid, or `Failure` with an error message\n   * if not.\n   * @public\n   */\n  public static toLiteralConditionValue(from: string): Result<QualifierConditionValue> {\n    return LiteralQualifierType.isValidLiteralConditionValue(from)\n      ? succeed(from)\n      : fail(`${from}: not a valid literal condition value.`);\n  }\n}\n"]}

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

@@ -0,0 +1,184 @@
+import { Collections, ICollectible, Result } from '@fgv/ts-utils';
+import { ConditionOperator, QualifierConditionValue, QualifierContextValue, QualifierMatchScore, QualifierTypeIndex, QualifierTypeName } from '../common';
+/**
+ * Interface for a qualifier type. A qualifier type implements the build and
+ * runtime semantics for some class of related qualifiers (e.g. language,
+ * territories, etc).
+ * @public
+ */
+export interface IQualifierType extends ICollectible<QualifierTypeName, QualifierTypeIndex> {
+    /**
+     * The name of the qualifier type.
+     */
+    readonly name: QualifierTypeName;
+    /**
+     * Unique key for this qualifier.
+     */
+    readonly key: QualifierTypeName;
+    /**
+     * Global index for this qualifier type. Immutable once set, either at
+     * construction or using {@link QualifierTypes.IQualifierType.setIndex | setIndex}.
+     */
+    readonly index: QualifierTypeIndex | undefined;
+    /**
+     * 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.
+     */
+    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.
+     */
+    isValidContextValue(value: string): value is QualifierContextValue;
+    /**
+     * Validates that a value and optional operator are valid for use in a condition
+     * for qualifiers of this type.
+     * @param value - The string value to validate.
+     * @param operator - An optional operator to validate. Defaults to 'matches'.
+     */
+    validateCondition(value: string, operator?: ConditionOperator): Result<QualifierConditionValue>;
+    /**
+     * 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.
+     */
+    validateContextValue(value: string): Result<QualifierContextValue>;
+    /**
+     * 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.
+     */
+    matches(condition: QualifierConditionValue, context: QualifierContextValue, operator: ConditionOperator): QualifierMatchScore;
+    /**
+     * Sets the index for this qualifier type.  Once set, index is
+     * immutable.
+     */
+    setIndex(index: number): Result<QualifierTypeIndex>;
+}
+/**
+ * Parameters used to create a base {@link QualifierTypes.QualifierType | qualifier type}.
+ * @public
+ */
+export interface IQualifierTypeCreateParams {
+    /**
+     * The name of the qualifier type. No default value.
+     */
+    name: string;
+    /**
+     * Global index for this qualifier type.
+     */
+    index?: number;
+    /**
+     * Flag indicating whether this qualifier type allows a list of values in a context.
+     * Defaults to `false`.
+     */
+    allowContextList?: boolean;
+}
+/**
+ * Abstract base class for qualifier types. Provides default implementations for
+ * the {@link QualifierTypes.IQualifierType | IQualifierType} interface.
+ * @public
+ */
+export declare abstract class QualifierType implements IQualifierType {
+    /**
+     * {@inheritdoc QualifierTypes.IQualifierType.name}
+     */
+    readonly name: QualifierTypeName;
+    /**
+     * {@inheritdoc QualifierTypes.IQualifierType.key}
+     */
+    get key(): QualifierTypeName;
+    /**
+     * {@inheritdoc QualifierTypes.IQualifierType.index}
+     */
+    get index(): QualifierTypeIndex | undefined;
+    protected readonly _collectible: Collections.Collectible<QualifierTypeName, QualifierTypeIndex>;
+    /**
+     * Flag indicating whether this qualifier type allows a list of values in a context.
+     * @public
+     */
+    readonly allowContextList: boolean;
+    /**
+     * Constructor for use by derived classes.
+     * @param name - The name of the qualifier type.
+     * @param allowContextList - Flag indicating whether this qualifier type allows a
+     * comma-separated list of runtime values in the context. Defaults to `false`.
+     */
+    protected constructor({ name, index, allowContextList }: IQualifierTypeCreateParams);
+    /**
+     * {@inheritdoc QualifierTypes.IQualifierType.isValidConditionValue}
+     */
+    abstract isValidConditionValue(value: string): value is QualifierConditionValue;
+    /**
+     * {@inheritdoc QualifierTypes.IQualifierType.isValidContextValue}
+     */
+    isValidContextValue(value: string): value is QualifierContextValue;
+    /**
+     * {@inheritdoc QualifierTypes.IQualifierType.validateCondition}
+     */
+    validateCondition(value: string, operator?: ConditionOperator): Result<QualifierConditionValue>;
+    /**
+     * {@inheritdoc QualifierTypes.IQualifierType.validateContextValue}
+     */
+    validateContextValue(value: string): Result<QualifierContextValue>;
+    /**
+     * {@inheritdoc QualifierTypes.IQualifierType.matches}
+     */
+    matches(condition: QualifierConditionValue, context: QualifierContextValue, operator: ConditionOperator): QualifierMatchScore;
+    /**
+     * {@inheritdoc QualifierTypes.IQualifierType.setIndex}
+     */
+    setIndex(index: number): Result<QualifierTypeIndex>;
+    /**
+     * {@inheritdoc Validate.isValidQualifierTypeName}
+     */
+    static isValidName(name: string): name is QualifierTypeName;
+    /**
+     * {@inheritdoc Validate.isValidQualifierTypeIndex}
+     */
+    static isValidIndex(index: number): index is QualifierTypeIndex;
+    /**
+     * Compares two qualifier types by index.
+     * @param t1 - The first qualifier type to compare.
+     * @param t2 - The second qualifier type to compare.
+     * @returns a number indicating the relative order of the two qualifier types.
+     */
+    static compare(t1: QualifierType, t2: QualifierType): number;
+    /**
+     * Matches a single condition value against a single context value.
+     * @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.
+     * @public
+     */
+    protected abstract _matchOne(condition: QualifierConditionValue, context: QualifierContextValue, operator: ConditionOperator): QualifierMatchScore;
+    /**
+     * Matches a single condition value against a list of context values.
+     * @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.
+     * @public
+     */
+    protected _matchList(condition: QualifierConditionValue, context: QualifierContextValue[], operator: ConditionOperator): QualifierMatchScore;
+    /**
+     * 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
+     */
+    protected static _splitContext(value: QualifierContextValue): QualifierContextValue[];
+}
+//# sourceMappingURL=qualifierType.d.ts.map

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

@@ -0,0 +1 @@
+{"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

@@ -0,0 +1,173 @@
+"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.QualifierType = void 0;
+const ts_utils_1 = require("@fgv/ts-utils");
+const common_1 = require("../common");
+/**
+ * Abstract base class for qualifier types. Provides default implementations for
+ * the {@link QualifierTypes.IQualifierType | IQualifierType} interface.
+ * @public
+ */
+class QualifierType {
+    /**
+     * {@inheritdoc QualifierTypes.IQualifierType.key}
+     */
+    get key() {
+        return this._collectible.key;
+    }
+    /**
+     * {@inheritdoc QualifierTypes.IQualifierType.index}
+     */
+    get index() {
+        return this._collectible.index;
+    }
+    /**
+     * Constructor for use by derived classes.
+     * @param name - The name of the qualifier type.
+     * @param allowContextList - Flag indicating whether this qualifier type allows a
+     * comma-separated list of runtime values in the context. Defaults to `false`.
+     */
+    constructor({ name, index, allowContextList }) {
+        this.name = common_1.Convert.qualifierTypeName.convert(name).orThrow();
+        this.allowContextList = allowContextList === true;
+        this._collectible = new ts_utils_1.Collections.Collectible({
+            key: this.name,
+            index: index,
+            indexConverter: common_1.Convert.qualifierTypeIndex
+        });
+    }
+    /**
+     * {@inheritdoc QualifierTypes.IQualifierType.isValidContextValue}
+     */
+    isValidContextValue(value) {
+        if (this.isValidConditionValue(value)) {
+            return true;
+        }
+        if (this.allowContextList) {
+            return value.split(',').every((v) => this.isValidConditionValue(v.trim()));
+        }
+        return false;
+    }
+    /**
+     * {@inheritdoc QualifierTypes.IQualifierType.validateCondition}
+     */
+    validateCondition(value, operator) {
+        operator = operator !== null && operator !== void 0 ? operator : 'matches';
+        if (operator !== 'matches') {
+            return (0, ts_utils_1.fail)(`${operator}: invalid condition operator`);
+        }
+        else if (!this.isValidConditionValue(value)) {
+            return (0, ts_utils_1.fail)(`${value}: invalid condition value for qualifierType ${this.name}`);
+        }
+        return (0, ts_utils_1.succeed)(value);
+    }
+    /**
+     * {@inheritdoc QualifierTypes.IQualifierType.validateContextValue}
+     */
+    validateContextValue(value) {
+        if (!this.isValidContextValue(value)) {
+            return (0, ts_utils_1.fail)(`${value}: invalid context value for qualifierType ${this.name}`);
+        }
+        return (0, ts_utils_1.succeed)(value);
+    }
+    /**
+     * {@inheritdoc QualifierTypes.IQualifierType.matches}
+     */
+    matches(condition, context, operator) {
+        if (this.allowContextList) {
+            return this._matchList(condition, QualifierType._splitContext(context), operator);
+        }
+        return this._matchOne(condition, context, operator);
+    }
+    /**
+     * {@inheritdoc QualifierTypes.IQualifierType.setIndex}
+     */
+    setIndex(index) {
+        return this._collectible.setIndex(index);
+    }
+    /**
+     * {@inheritdoc Validate.isValidQualifierTypeName}
+     */
+    static isValidName(name) {
+        return common_1.Validate.isValidQualifierTypeName(name);
+    }
+    /**
+     * {@inheritdoc Validate.isValidQualifierTypeIndex}
+     */
+    static isValidIndex(index) {
+        return common_1.Validate.isValidQualifierTypeIndex(index);
+    }
+    /**
+     * Compares two qualifier types by index.
+     * @param t1 - The first qualifier type to compare.
+     * @param t2 - The second qualifier type to compare.
+     * @returns a number indicating the relative order of the two qualifier types.
+     */
+    static compare(t1, t2) {
+        var _a, _b;
+        const i1 = (_a = t1._collectible.index) !== null && _a !== void 0 ? _a : -1;
+        const i2 = (_b = t2._collectible.index) !== null && _b !== void 0 ? _b : -1;
+        let diff = i1 - i2;
+        if (diff === 0) {
+            diff = t1.name.localeCompare(t2.name);
+        }
+        return diff;
+    }
+    /**
+     * Matches a single condition value against a list of context values.
+     * @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.
+     * @public
+     */
+    _matchList(condition, context, operator) {
+        const scorePerPosition = 1 / context.length;
+        let baseScore = common_1.PerfectMatch - scorePerPosition;
+        for (let i = 0; i < context.length; i++) {
+            const score = this._matchOne(condition, context[i], operator);
+            if (score > common_1.NoMatch) {
+                const adjusted = baseScore + scorePerPosition * score;
+                if (common_1.Validate.isValidQualifierMatchScore(adjusted)) {
+                    return adjusted;
+                }
+            }
+            baseScore -= scorePerPosition;
+        }
+        return common_1.NoMatch;
+    }
+    /**
+     * 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
+     */
+    static _splitContext(value) {
+        return value.split(',').map((s) => s.trim());
+    }
+}
+exports.QualifierType = QualifierType;
+//# sourceMappingURL=qualifierType.js.map

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

@@ -0,0 +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"]}

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

@@ -0,0 +1,40 @@
+import { Collections, Result, ValidatingConvertingCollector } from '@fgv/ts-utils';
+import { QualifierType } from './qualifierType';
+import { QualifierTypeName } from '../common';
+/**
+ * Parameters for creating a new {@link QualifierTypes.QualifierTypeCollector | QualifierTypeCollector}.
+ * @public
+ */
+export interface IQualifierTypeCollectorCreateParams {
+    /**
+     * Optional list of {@link QualifierTypes.QualifierType | QualifierTypes} to add to the collector
+     * on creation.
+     */
+    qualifierTypes?: QualifierType[];
+}
+/**
+ * Collector for {@link QualifierTypes.QualifierType | QualifierType} objects.
+ * @public
+ */
+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.
+     */
+    protected constructor({ qualifierTypes }: IQualifierTypeCollectorCreateParams);
+    /**
+     * Creates a new {@link QualifierTypes.QualifierTypeCollector | QualifierTypeCollector} object.
+     * @param params - Optional {@link QualifierTypes.IQualifierTypeCollectorCreateParams | parameters}
+     * used to create the collector.
+     * @returns `Success` with the new collector if successful, or `Failure` if not.
+     */
+    static create(params?: IQualifierTypeCollectorCreateParams): Result<QualifierTypeCollector>;
+    protected static _qualifierTypeFactory(key: QualifierTypeName, index: number, value: QualifierType): Result<QualifierType>;
+    protected static _toQualifierType(from: unknown): Result<QualifierType>;
+}
+/**
+ * Interface exposing non-mutating members of a {@link QualifierTypes.QualifierTypeCollector | QualifierTypeCollector}.
+ * @public
+ */
+export type ReadOnlyQualifierTypeCollector = Collections.IReadOnlyValidatingCollector<QualifierType>;
+//# sourceMappingURL=qualifierTypeCollector.d.ts.map

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

@@ -0,0 +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"}