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

package/lib/packlets/config/systemConfiguration.js

@@ -0,0 +1,172 @@
+"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.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SystemConfiguration = void 0;
+exports.updateSystemConfigurationQualifierDefaultValues = updateSystemConfigurationQualifierDefaultValues;
+const ts_utils_1 = require("@fgv/ts-utils");
+const QualifierTypes = __importStar(require("../qualifier-types"));
+const ResourceTypes = __importStar(require("../resource-types"));
+const qualifier_types_1 = require("../qualifier-types");
+const qualifiers_1 = require("../qualifiers");
+const resource_types_1 = require("../resource-types");
+const convert_1 = require("./convert");
+const ts_json_base_1 = require("@fgv/ts-json-base");
+/**
+ * Creates a copy of the provided {@link Config.Model.ISystemConfiguration | system configuration}
+ * with updated qualifier default values.
+ * @param config - The base {@link Config.Model.ISystemConfiguration | system configuration} to copy.
+ * @param qualifierDefaultValues - Map of qualifier names to default values. Use `null` to remove existing values.
+ * @returns `Success` with the updated {@link Config.Model.ISystemConfiguration | system configuration}
+ * if successful, `Failure` with an error message otherwise.
+ * @public
+ */
+function updateSystemConfigurationQualifierDefaultValues(config, qualifierDefaultValues // eslint-disable-line @rushstack/no-new-null
+) {
+    // Create a copy of the config
+    return (0, ts_json_base_1.sanitizeJsonObject)(config).onSuccess((updatedConfig) => {
+        // Create a map of existing qualifier names for validation
+        const existingQualifierNames = new Set(updatedConfig.qualifiers.map((q) => q.name));
+        // Validate that all specified qualifiers exist in the configuration
+        for (const qualifierName of Object.keys(qualifierDefaultValues)) {
+            if (!existingQualifierNames.has(qualifierName)) {
+                return (0, ts_utils_1.fail)(`Qualifier '${qualifierName}' not found in system configuration`);
+            }
+        }
+        // Update qualifier default values
+        updatedConfig.qualifiers = updatedConfig.qualifiers.map((qualifier) => {
+            if (qualifier.name in qualifierDefaultValues) {
+                const newDefaultValue = qualifierDefaultValues[qualifier.name];
+                // Create a copy of the qualifier
+                const updatedQualifier = Object.assign({}, qualifier);
+                if (newDefaultValue === null) {
+                    // Remove the default value
+                    delete updatedQualifier.defaultValue;
+                }
+                else {
+                    // Set the new default value
+                    updatedQualifier.defaultValue = newDefaultValue;
+                }
+                return updatedQualifier;
+            }
+            return qualifier;
+        });
+        return (0, ts_utils_1.succeed)(updatedConfig);
+    });
+}
+/**
+ * A system configuration for both runtime or build.
+ * @public
+ */
+class SystemConfiguration {
+    /**
+     * The name of this system configuration.
+     */
+    get name() {
+        return this._config.name;
+    }
+    /**
+     * The description of this system configuration.
+     */
+    get description() {
+        return this._config.description;
+    }
+    /**
+     * Constructs a new instance of a {@link Config.SystemConfiguration | SystemConfiguration} from the
+     * supplied {@link Config.Model.ISystemConfiguration | system configuration}.
+     * @param config - The {@link Config.Model.ISystemConfiguration | system configuration} to use.
+     * @public
+     */
+    constructor(config) {
+        this._config = config;
+        this.qualifierTypes = qualifier_types_1.QualifierTypeCollector.create({
+            qualifierTypes: (0, ts_utils_1.mapResults)(config.qualifierTypes.map(QualifierTypes.createQualifierTypeFromSystemConfig)).orThrow()
+        }).orThrow();
+        this.qualifiers = qualifiers_1.QualifierCollector.create({
+            qualifierTypes: this.qualifierTypes,
+            qualifiers: config.qualifiers
+        }).orThrow();
+        this.resourceTypes = resource_types_1.ResourceTypeCollector.create({
+            resourceTypes: (0, ts_utils_1.mapResults)(config.resourceTypes.map(ResourceTypes.createResourceTypeFromConfig)).orThrow()
+        }).orThrow();
+    }
+    /**
+     * Creates a new {@link Config.SystemConfiguration | SystemConfiguration} from the supplied
+     * {@link Config.Model.ISystemConfiguration | system configuration}.
+     * @param config - The {@link Config.Model.ISystemConfiguration | system configuration} to use.
+     * @param initParams - Optional {@link Config.ISystemConfigurationInitParams | initialization parameters}.
+     * @returns `Success` with the new {@link Config.SystemConfiguration | SystemConfiguration}
+     * if successful, `Failure` with an error message otherwise.
+     * @public
+     */
+    static create(config, initParams) {
+        if (initParams === null || initParams === void 0 ? void 0 : initParams.qualifierDefaultValues) {
+            return updateSystemConfigurationQualifierDefaultValues(config, initParams.qualifierDefaultValues).onSuccess((updatedConfig) => (0, ts_utils_1.captureResult)(() => new SystemConfiguration(updatedConfig)));
+        }
+        return (0, ts_utils_1.captureResult)(() => new SystemConfiguration(config));
+    }
+    /**
+     * Returns the {@link Config.Model.ISystemConfiguration | system configuration} that this
+     * {@link Config.SystemConfiguration | SystemConfiguration} was created from.
+     * @returns `Success` with the {@link Config.Model.ISystemConfiguration | system configuration}
+     * if successful, `Failure` with an error message otherwise.
+     * @public
+     */
+    getConfig() {
+        return convert_1.systemConfiguration.convert(this._config);
+    }
+}
+exports.SystemConfiguration = SystemConfiguration;
+//# sourceMappingURL=systemConfiguration.js.map

package/lib/packlets/config/systemConfiguration.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"systemConfiguration.js","sourceRoot":"","sources":["../../../src/packlets/config/systemConfiguration.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, mapResults, Result, fail, succeed } from '@fgv/ts-utils';\nimport * as QualifierTypes from '../qualifier-types';\nimport * as ResourceTypes from '../resource-types';\nimport { QualifierTypeCollector, ReadOnlyQualifierTypeCollector } from '../qualifier-types';\nimport { IReadOnlyQualifierCollector, QualifierCollector } from '../qualifiers';\nimport { ReadOnlyResourceTypeCollector, ResourceTypeCollector } from '../resource-types';\nimport { ISystemConfiguration } from './json';\nimport { systemConfiguration } from './convert';\nimport { sanitizeJsonObject } from '@fgv/ts-json-base';\n\n/**\n * Parameters used to initialize a {@link Config.SystemConfiguration | SystemConfiguration}.\n * @public\n */\nexport interface ISystemConfigurationInitParams {\n  /**\n   * Optional map of qualifier names to default values. If provided, qualifiers\n   * in the system configuration will be updated with these default values.\n   * Use `null` as the value to remove an existing default value.\n   */\n  qualifierDefaultValues?: Record<string, string | null>; // eslint-disable-line @rushstack/no-new-null\n}\n\n/**\n * Creates a copy of the provided {@link Config.Model.ISystemConfiguration | system configuration}\n * with updated qualifier default values.\n * @param config - The base {@link Config.Model.ISystemConfiguration | system configuration} to copy.\n * @param qualifierDefaultValues - Map of qualifier names to default values. Use `null` to remove existing values.\n * @returns `Success` with the updated {@link Config.Model.ISystemConfiguration | system configuration}\n * if successful, `Failure` with an error message otherwise.\n * @public\n */\nexport function updateSystemConfigurationQualifierDefaultValues(\n  config: ISystemConfiguration,\n  qualifierDefaultValues: Record<string, string | null> // eslint-disable-line @rushstack/no-new-null\n): Result<ISystemConfiguration> {\n  // Create a copy of the config\n  return sanitizeJsonObject<ISystemConfiguration>(config).onSuccess((updatedConfig) => {\n    // Create a map of existing qualifier names for validation\n    const existingQualifierNames = new Set(updatedConfig.qualifiers.map((q) => q.name));\n\n    // Validate that all specified qualifiers exist in the configuration\n    for (const qualifierName of Object.keys(qualifierDefaultValues)) {\n      if (!existingQualifierNames.has(qualifierName)) {\n        return fail(`Qualifier '${qualifierName}' not found in system configuration`);\n      }\n    }\n\n    // Update qualifier default values\n    updatedConfig.qualifiers = updatedConfig.qualifiers.map((qualifier) => {\n      if (qualifier.name in qualifierDefaultValues) {\n        const newDefaultValue = qualifierDefaultValues[qualifier.name];\n\n        // Create a copy of the qualifier\n        const updatedQualifier = { ...qualifier };\n\n        if (newDefaultValue === null) {\n          // Remove the default value\n          delete updatedQualifier.defaultValue;\n        } else {\n          // Set the new default value\n          updatedQualifier.defaultValue = newDefaultValue;\n        }\n\n        return updatedQualifier;\n      }\n      return qualifier;\n    });\n\n    return succeed(updatedConfig);\n  });\n}\n\n/**\n * A system configuration for both runtime or build.\n * @public\n */\nexport class SystemConfiguration {\n  /**\n   * The name of this system configuration.\n   */\n  public get name(): string | undefined {\n    return this._config.name;\n  }\n\n  /**\n   * The description of this system configuration.\n   */\n  public get description(): string | undefined {\n    return this._config.description;\n  }\n\n  /**\n   * The {@link QualifierTypes.QualifierTypeCollector | qualifier types} that this system configuration uses.\n   */\n  public readonly qualifierTypes: ReadOnlyQualifierTypeCollector;\n\n  /**\n   * The {@link QualifierTypes.QualifierTypeCollector | qualifier types} that this system configuration uses.\n   * @public\n   */\n  public readonly qualifiers: IReadOnlyQualifierCollector;\n\n  /**\n   * The {@link ResourceTypes.ResourceTypeCollector | resource types} that this system configuration uses.\n   */\n  public readonly resourceTypes: ReadOnlyResourceTypeCollector;\n\n  private readonly _config: ISystemConfiguration;\n\n  /**\n   * Constructs a new instance of a {@link Config.SystemConfiguration | SystemConfiguration} from the\n   * supplied {@link Config.Model.ISystemConfiguration | system configuration}.\n   * @param config - The {@link Config.Model.ISystemConfiguration | system configuration} to use.\n   * @public\n   */\n  protected constructor(config: ISystemConfiguration) {\n    this._config = config;\n\n    this.qualifierTypes = QualifierTypeCollector.create({\n      qualifierTypes: mapResults(\n        config.qualifierTypes.map(QualifierTypes.createQualifierTypeFromSystemConfig)\n      ).orThrow()\n    }).orThrow();\n\n    this.qualifiers = QualifierCollector.create({\n      qualifierTypes: this.qualifierTypes,\n      qualifiers: config.qualifiers\n    }).orThrow();\n\n    this.resourceTypes = ResourceTypeCollector.create({\n      resourceTypes: mapResults(\n        config.resourceTypes.map(ResourceTypes.createResourceTypeFromConfig)\n      ).orThrow()\n    }).orThrow();\n  }\n\n  /**\n   * Creates a new {@link Config.SystemConfiguration | SystemConfiguration} from the supplied\n   * {@link Config.Model.ISystemConfiguration | system configuration}.\n   * @param config - The {@link Config.Model.ISystemConfiguration | system configuration} to use.\n   * @param initParams - Optional {@link Config.ISystemConfigurationInitParams | initialization parameters}.\n   * @returns `Success` with the new {@link Config.SystemConfiguration | SystemConfiguration}\n   * if successful, `Failure` with an error message otherwise.\n   * @public\n   */\n  public static create(\n    config: ISystemConfiguration,\n    initParams?: ISystemConfigurationInitParams\n  ): Result<SystemConfiguration> {\n    if (initParams?.qualifierDefaultValues) {\n      return updateSystemConfigurationQualifierDefaultValues(\n        config,\n        initParams.qualifierDefaultValues\n      ).onSuccess((updatedConfig) => captureResult(() => new SystemConfiguration(updatedConfig)));\n    }\n    return captureResult(() => new SystemConfiguration(config));\n  }\n\n  /**\n   * Returns the {@link Config.Model.ISystemConfiguration | system configuration} that this\n   * {@link Config.SystemConfiguration | SystemConfiguration} was created from.\n   * @returns `Success` with the {@link Config.Model.ISystemConfiguration | system configuration}\n   * if successful, `Failure` with an error message otherwise.\n   * @public\n   */\n  public getConfig(): Result<ISystemConfiguration> {\n    return systemConfiguration.convert(this._config);\n  }\n}\n"]}

package/lib/packlets/context/contextDecls.d.ts

@@ -0,0 +1,49 @@
+import { QualifierContextValue, QualifierName } from '../common';
+import { Qualifier } from '../qualifiers';
+/**
+ * Options to control matching of conditions against a context.
+ * @public
+ */
+export interface IContextMatchOptions {
+    /**
+     * If true, then conditions which would otherwise yield
+     * {@link NoMatch | NoMatch} but have a defined {@link Conditions.Condition.scoreAsDefault | scoreAsDefault}
+     * will yield `scoreAsDefault`instead of `NoMatch`.
+     */
+    acceptDefaultScore?: boolean;
+    /**
+     * If true, then conditions for which a corresponding values is not present in the
+     * context being matched will yield `undefined` instead of `NoMatch`.
+     */
+    partialContextMatch?: boolean;
+}
+/**
+ * Non-validated declaration of a single context qualifier value.
+ * @public
+ */
+export interface IContextQualifierValueDecl {
+    qualifier: string;
+    value: string;
+}
+/**
+ * Non-validated declaration of a context, consisting of named
+ * values.
+ * @public
+ */
+export type IContextDecl = Record<string, string>;
+/**
+ * Validated declaration of a single context qualifier value.
+ * @public
+ */
+export interface IValidatedContextQualifierValueDecl {
+    qualifier: Qualifier;
+    value: QualifierContextValue;
+}
+/**
+ * Validated declaration of a context, a record with strongly-typed
+ * {@link QualifierTypeName | qualifier type names} as keys and
+ * {@link QualifierContextValue | qualifier context values} as values.
+ * @public
+ */
+export type IValidatedContextDecl = Record<QualifierName, QualifierContextValue>;
+//# sourceMappingURL=contextDecls.d.ts.map

package/lib/packlets/context/contextDecls.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contextDecls.d.ts","sourceRoot":"","sources":["../../../src/packlets/context/contextDecls.ts"],"names":[],"mappings":"AAsBA,OAAO,EAAE,qBAAqB,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AACjE,OAAO,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAE1C;;;GAGG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;;OAIG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAE7B;;;OAGG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAC;CAC/B;AAED;;;GAGG;AACH,MAAM,WAAW,0BAA0B;IACzC,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;GAIG;AACH,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAElD;;;GAGG;AACH,MAAM,WAAW,mCAAmC;IAClD,SAAS,EAAE,SAAS,CAAC;IACrB,KAAK,EAAE,qBAAqB,CAAC;CAC9B;AAED;;;;;GAKG;AACH,MAAM,MAAM,qBAAqB,GAAG,MAAM,CAAC,aAAa,EAAE,qBAAqB,CAAC,CAAC"}

package/lib/packlets/context/contextDecls.js

@@ -0,0 +1,24 @@
+"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 });
+//# sourceMappingURL=contextDecls.js.map

package/lib/packlets/context/contextDecls.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contextDecls.js","sourceRoot":"","sources":["../../../src/packlets/context/contextDecls.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;GAoBG","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 { QualifierContextValue, QualifierName } from '../common';\nimport { Qualifier } from '../qualifiers';\n\n/**\n * Options to control matching of conditions against a context.\n * @public\n */\nexport interface IContextMatchOptions {\n  /**\n   * If true, then conditions which would otherwise yield\n   * {@link NoMatch | NoMatch} but have a defined {@link Conditions.Condition.scoreAsDefault | scoreAsDefault}\n   * will yield `scoreAsDefault`instead of `NoMatch`.\n   */\n  acceptDefaultScore?: boolean;\n\n  /**\n   * If true, then conditions for which a corresponding values is not present in the\n   * context being matched will yield `undefined` instead of `NoMatch`.\n   */\n  partialContextMatch?: boolean;\n}\n\n/**\n * Non-validated declaration of a single context qualifier value.\n * @public\n */\nexport interface IContextQualifierValueDecl {\n  qualifier: string;\n  value: string;\n}\n\n/**\n * Non-validated declaration of a context, consisting of named\n * values.\n * @public\n */\nexport type IContextDecl = Record<string, string>;\n\n/**\n * Validated declaration of a single context qualifier value.\n * @public\n */\nexport interface IValidatedContextQualifierValueDecl {\n  qualifier: Qualifier;\n  value: QualifierContextValue;\n}\n\n/**\n * Validated declaration of a context, a record with strongly-typed\n * {@link QualifierTypeName | qualifier type names} as keys and\n * {@link QualifierContextValue | qualifier context values} as values.\n * @public\n */\nexport type IValidatedContextDecl = Record<QualifierName, QualifierContextValue>;\n"]}

package/lib/packlets/context/contextToken.d.ts

@@ -0,0 +1,111 @@
+import { Result } from '@fgv/ts-utils';
+import { Helpers as CommonHelpers } from '../common';
+import { IValidatedContextQualifierValueDecl, IValidatedContextDecl } from './contextDecls';
+import { IReadOnlyQualifierCollector, Qualifier } from '../qualifiers';
+/**
+ * Helper class to parse and validate context tokens.
+ * @public
+ */
+export declare class ContextTokens {
+    /**
+     * The {@link Qualifiers.IReadOnlyQualifierCollector | qualifier collector} used to validate
+     * qualifier names and values.
+     */
+    readonly qualifiers: IReadOnlyQualifierCollector;
+    /**
+     * Constructs a new {@link Context.ContextTokens | ContextTokens } instance.
+     * @param qualifiers - the {@link Qualifiers.IReadOnlyQualifierCollector | qualifier collector} to use
+     */
+    constructor(qualifiers: IReadOnlyQualifierCollector);
+    /**
+     * Parses a {@link ContextQualifierToken | context qualifier token} string and validates the parts
+     * against the qualifiers present in the {@link Context.ContextTokens.qualifiers | qualifier collector}.
+     * @param token - the token string to parse.
+     * @returns `Success` with the {@link Context.IValidatedContextQualifierValueDecl | validated context qualifier value declaration}
+     * if successful, `Failure` with an error message if not.
+     */
+    parseContextQualifierToken(token: string): Result<IValidatedContextQualifierValueDecl>;
+    /**
+     * Parses a {@link ContextToken | context token} string and validates the parts
+     * against the qualifiers present in the {@link Context.ContextTokens.qualifiers | qualifier collector}.
+     * @param token - the token string to parse.
+     * @returns `Success` with the array of {@link Context.IValidatedContextQualifierValueDecl | validated context qualifier value declarations}
+     * if successful, `Failure` with an error message if not.
+     */
+    parseContextToken(token: string): Result<IValidatedContextQualifierValueDecl[]>;
+    /**
+     * Validates the {@link Helpers.IContextTokenParts | parts} of a {@link ContextToken | context token}.
+     * @param parts - the parts to validate
+     * @returns `Success` with the validated declaration if successful, `Failure` with an error message if not.
+     */
+    validateContextTokenParts(parts: CommonHelpers.IContextTokenParts): Result<IValidatedContextQualifierValueDecl>;
+    /**
+     * Given a value, finds a single token-optional qualifier that matches the value.
+     * Fails if no qualifiers match, or if more than one qualifier matches.
+     * @param value - the value to match.
+     * @returns `Success` with the matching qualifier if successful, `Failure` with an error message if not.
+     */
+    findQualifierForValue(value: string): Result<Qualifier>;
+    /**
+     * Converts a {@link ContextToken | context token} to a validated partial context.
+     * @param token - the context token to convert
+     * @returns `Success` with the validated partial context if successful, `Failure` with an error message if not.
+     */
+    contextTokenToPartialContext(token: string): Result<IValidatedContextDecl>;
+    /**
+     * Converts a validated partial context to a {@link ContextToken | context token}.
+     * @param context - the validated partial context to convert
+     * @returns `Success` with the context token if successful, `Failure` with an error message if not.
+     */
+    partialContextToContextToken(context: IValidatedContextDecl): Result<string>;
+    /**
+     * Parses a {@link ContextQualifierToken | context qualifier token} and validates it against the qualifiers
+     * present in the supplied {@link Qualifiers.IReadOnlyQualifierCollector | qualifier collector}.
+     * @param token - the token string to parse.
+     * @param qualifiers - the {@link Qualifiers.IReadOnlyQualifierCollector | qualifier collector} to use
+     * @returns `Success` with a {@link Context.IValidatedContextQualifierValueDecl | validated context qualifier value declaration} if successful,
+     * `Failure` with an error message if not.
+     */
+    static parseContextQualifierToken(token: string, qualifiers: IReadOnlyQualifierCollector): Result<IValidatedContextQualifierValueDecl>;
+    /**
+     * Parses a {@link ContextToken | context token} and validates it against the qualifiers
+     * present in the supplied {@link Qualifiers.IReadOnlyQualifierCollector | qualifier collector}.
+     * @param token - the token string to parse.
+     * @param qualifiers - the {@link Qualifiers.IReadOnlyQualifierCollector | qualifier collector} to use
+     * @returns `Success` with an array of {@link Context.IValidatedContextQualifierValueDecl | validated context qualifier value declarations}
+     * if successful, `Failure` with an error message if not
+     */
+    static parseContextToken(token: string, qualifiers: IReadOnlyQualifierCollector): Result<IValidatedContextQualifierValueDecl[]>;
+    /**
+     * Validates the parts of a context token against the qualifiers present in the supplied
+     * {@link Qualifiers.IReadOnlyQualifierCollector | qualifier collector}.
+     * @param parts - the {@link Helpers.IContextTokenParts | context token parts} to validate.
+     * @param qualifiers - the {@link Qualifiers.IReadOnlyQualifierCollector | qualifier collector} used to
+     * validate qualifier names and values.
+     * @returns `Success` with a {@link Context.IValidatedContextQualifierValueDecl | validated context qualifier value declaration} if successful,
+     * `Failure` with an error message if not.
+     */
+    static validateContextTokenParts(parts: CommonHelpers.IContextTokenParts, qualifiers: IReadOnlyQualifierCollector): Result<IValidatedContextQualifierValueDecl>;
+    /**
+     * Given a value and a set of qualifiers, finds a single token-optional qualifier that matches the value.
+     * Fails if no qualifiers match, or if more than one qualifier matches.
+     * @param value - the value to match.
+     * @param qualifiers - the qualifiers to match against.
+     * @returns `Success` with the matching qualifier if successful, `Failure` with an error message if not.
+     */
+    static findQualifierForValue(value: string, qualifiers: IReadOnlyQualifierCollector): Result<Qualifier>;
+    /**
+     * Converts a {@link ContextToken | context token} to a validated partial context.
+     * @param token - the context token to convert
+     * @param qualifiers - the {@link Qualifiers.IReadOnlyQualifierCollector | qualifier collector} to use
+     * @returns `Success` with the validated partial context if successful, `Failure` with an error message if not.
+     */
+    static contextTokenToPartialContext(token: string, qualifiers: IReadOnlyQualifierCollector): Result<IValidatedContextDecl>;
+    /**
+     * Converts a validated partial context to a {@link ContextToken | context token}.
+     * @param context - the validated partial context to convert
+     * @returns `Success` with the context token if successful, `Failure` with an error message if not.
+     */
+    static partialContextToContextToken(context: IValidatedContextDecl): Result<string>;
+}
+//# sourceMappingURL=contextToken.d.ts.map

package/lib/packlets/context/contextToken.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contextToken.d.ts","sourceRoot":"","sources":["../../../src/packlets/context/contextToken.ts"],"names":[],"mappings":"AAsBA,OAAO,EAAc,MAAM,EAAiB,MAAM,eAAe,CAAC;AAClE,OAAO,EAAE,OAAO,IAAI,aAAa,EAAwC,MAAM,WAAW,CAAC;AAC3F,OAAO,EAAE,mCAAmC,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAC;AAC5F,OAAO,EAAE,2BAA2B,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAEvE;;;GAGG;AACH,qBAAa,aAAa;IACxB;;;OAGG;IACH,SAAgB,UAAU,EAAE,2BAA2B,CAAC;IAExD;;;OAGG;gBACgB,UAAU,EAAE,2BAA2B;IAI1D;;;;;;OAMG;IACI,0BAA0B,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC,mCAAmC,CAAC;IAI7F;;;;;;OAMG;IACI,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC,mCAAmC,EAAE,CAAC;IAItF;;;;OAIG;IACI,yBAAyB,CAC9B,KAAK,EAAE,aAAa,CAAC,kBAAkB,GACtC,MAAM,CAAC,mCAAmC,CAAC;IAI9C;;;;;OAKG;IACI,qBAAqB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC,SAAS,CAAC;IAI9D;;;;OAIG;IACI,4BAA4B,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC,qBAAqB,CAAC;IAIjF;;;;OAIG;IACI,4BAA4B,CAAC,OAAO,EAAE,qBAAqB,GAAG,MAAM,CAAC,MAAM,CAAC;IAInF;;;;;;;OAOG;WACW,0BAA0B,CACtC,KAAK,EAAE,MAAM,EACb,UAAU,EAAE,2BAA2B,GACtC,MAAM,CAAC,mCAAmC,CAAC;IAM9C;;;;;;;OAOG;WACW,iBAAiB,CAC7B,KAAK,EAAE,MAAM,EACb,UAAU,EAAE,2BAA2B,GACtC,MAAM,CAAC,mCAAmC,EAAE,CAAC;IAMhD;;;;;;;;OAQG;WACW,yBAAyB,CACrC,KAAK,EAAE,aAAa,CAAC,kBAAkB,EACvC,UAAU,EAAE,2BAA2B,GACtC,MAAM,CAAC,mCAAmC,CAAC;IAgB9C;;;;;;OAMG;WACW,qBAAqB,CACjC,KAAK,EAAE,MAAM,EACb,UAAU,EAAE,2BAA2B,GACtC,MAAM,CAAC,SAAS,CAAC;IAgBpB;;;;;OAKG;WACW,4BAA4B,CACxC,KAAK,EAAE,MAAM,EACb,UAAU,EAAE,2BAA2B,GACtC,MAAM,CAAC,qBAAqB,CAAC;IAoBhC;;;;OAIG;WACW,4BAA4B,CAAC,OAAO,EAAE,qBAAqB,GAAG,MAAM,CAAC,MAAM,CAAC;CAsB3F"}

package/lib/packlets/context/contextToken.js

@@ -0,0 +1,206 @@
+"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.ContextTokens = void 0;
+const ts_utils_1 = require("@fgv/ts-utils");
+const common_1 = require("../common");
+/**
+ * Helper class to parse and validate context tokens.
+ * @public
+ */
+class ContextTokens {
+    /**
+     * Constructs a new {@link Context.ContextTokens | ContextTokens } instance.
+     * @param qualifiers - the {@link Qualifiers.IReadOnlyQualifierCollector | qualifier collector} to use
+     */
+    constructor(qualifiers) {
+        this.qualifiers = qualifiers;
+    }
+    /**
+     * Parses a {@link ContextQualifierToken | context qualifier token} string and validates the parts
+     * against the qualifiers present in the {@link Context.ContextTokens.qualifiers | qualifier collector}.
+     * @param token - the token string to parse.
+     * @returns `Success` with the {@link Context.IValidatedContextQualifierValueDecl | validated context qualifier value declaration}
+     * if successful, `Failure` with an error message if not.
+     */
+    parseContextQualifierToken(token) {
+        return ContextTokens.parseContextQualifierToken(token, this.qualifiers);
+    }
+    /**
+     * Parses a {@link ContextToken | context token} string and validates the parts
+     * against the qualifiers present in the {@link Context.ContextTokens.qualifiers | qualifier collector}.
+     * @param token - the token string to parse.
+     * @returns `Success` with the array of {@link Context.IValidatedContextQualifierValueDecl | validated context qualifier value declarations}
+     * if successful, `Failure` with an error message if not.
+     */
+    parseContextToken(token) {
+        return ContextTokens.parseContextToken(token, this.qualifiers);
+    }
+    /**
+     * Validates the {@link Helpers.IContextTokenParts | parts} of a {@link ContextToken | context token}.
+     * @param parts - the parts to validate
+     * @returns `Success` with the validated declaration if successful, `Failure` with an error message if not.
+     */
+    validateContextTokenParts(parts) {
+        return ContextTokens.validateContextTokenParts(parts, this.qualifiers);
+    }
+    /**
+     * Given a value, finds a single token-optional qualifier that matches the value.
+     * Fails if no qualifiers match, or if more than one qualifier matches.
+     * @param value - the value to match.
+     * @returns `Success` with the matching qualifier if successful, `Failure` with an error message if not.
+     */
+    findQualifierForValue(value) {
+        return ContextTokens.findQualifierForValue(value, this.qualifiers);
+    }
+    /**
+     * Converts a {@link ContextToken | context token} to a validated partial context.
+     * @param token - the context token to convert
+     * @returns `Success` with the validated partial context if successful, `Failure` with an error message if not.
+     */
+    contextTokenToPartialContext(token) {
+        return ContextTokens.contextTokenToPartialContext(token, this.qualifiers);
+    }
+    /**
+     * Converts a validated partial context to a {@link ContextToken | context token}.
+     * @param context - the validated partial context to convert
+     * @returns `Success` with the context token if successful, `Failure` with an error message if not.
+     */
+    partialContextToContextToken(context) {
+        return ContextTokens.partialContextToContextToken(context);
+    }
+    /**
+     * Parses a {@link ContextQualifierToken | context qualifier token} and validates it against the qualifiers
+     * present in the supplied {@link Qualifiers.IReadOnlyQualifierCollector | qualifier collector}.
+     * @param token - the token string to parse.
+     * @param qualifiers - the {@link Qualifiers.IReadOnlyQualifierCollector | qualifier collector} to use
+     * @returns `Success` with a {@link Context.IValidatedContextQualifierValueDecl | validated context qualifier value declaration} if successful,
+     * `Failure` with an error message if not.
+     */
+    static parseContextQualifierToken(token, qualifiers) {
+        return common_1.Helpers.parseContextQualifierTokenParts(token).onSuccess((parts) => {
+            return ContextTokens.validateContextTokenParts(parts, qualifiers);
+        });
+    }
+    /**
+     * Parses a {@link ContextToken | context token} and validates it against the qualifiers
+     * present in the supplied {@link Qualifiers.IReadOnlyQualifierCollector | qualifier collector}.
+     * @param token - the token string to parse.
+     * @param qualifiers - the {@link Qualifiers.IReadOnlyQualifierCollector | qualifier collector} to use
+     * @returns `Success` with an array of {@link Context.IValidatedContextQualifierValueDecl | validated context qualifier value declarations}
+     * if successful, `Failure` with an error message if not
+     */
+    static parseContextToken(token, qualifiers) {
+        return common_1.Helpers.parseContextTokenParts(token).onSuccess((parts) => {
+            return (0, ts_utils_1.mapResults)(parts.map((part) => ContextTokens.validateContextTokenParts(part, qualifiers)));
+        });
+    }
+    /**
+     * Validates the parts of a context token against the qualifiers present in the supplied
+     * {@link Qualifiers.IReadOnlyQualifierCollector | qualifier collector}.
+     * @param parts - the {@link Helpers.IContextTokenParts | context token parts} to validate.
+     * @param qualifiers - the {@link Qualifiers.IReadOnlyQualifierCollector | qualifier collector} used to
+     * validate qualifier names and values.
+     * @returns `Success` with a {@link Context.IValidatedContextQualifierValueDecl | validated context qualifier value declaration} if successful,
+     * `Failure` with an error message if not.
+     */
+    static validateContextTokenParts(parts, qualifiers) {
+        const qualifierLookup = parts.qualifier === undefined
+            ? ContextTokens.findQualifierForValue(parts.value, qualifiers)
+            : qualifiers.getByNameOrToken(parts.qualifier);
+        return qualifierLookup.onSuccess((qualifier) => {
+            return qualifier.type
+                .validateContextValue(parts.value)
+                .onSuccess((value) => {
+                return (0, ts_utils_1.succeed)({ qualifier, value });
+            })
+                .withDetail('failure', 'success');
+        });
+    }
+    /**
+     * Given a value and a set of qualifiers, finds a single token-optional qualifier that matches the value.
+     * Fails if no qualifiers match, or if more than one qualifier matches.
+     * @param value - the value to match.
+     * @param qualifiers - the qualifiers to match against.
+     * @returns `Success` with the matching qualifier if successful, `Failure` with an error message if not.
+     */
+    static findQualifierForValue(value, qualifiers) {
+        const matched = [];
+        for (const qualifier of qualifiers.values()) {
+            if (qualifier.tokenIsOptional && qualifier.validateContextValue(value).isSuccess()) {
+                matched.push(qualifier);
+            }
+        }
+        if (matched.length === 0) {
+            return (0, ts_utils_1.fail)(`${value}: does not match any qualifier`);
+        }
+        if (matched.length > 1) {
+            return (0, ts_utils_1.fail)(`${value}: matches multiple qualifiers (${matched.map((q) => q.name).join(', ')})`);
+        }
+        return (0, ts_utils_1.succeed)(matched[0]);
+    }
+    /**
+     * Converts a {@link ContextToken | context token} to a validated partial context.
+     * @param token - the context token to convert
+     * @param qualifiers - the {@link Qualifiers.IReadOnlyQualifierCollector | qualifier collector} to use
+     * @returns `Success` with the validated partial context if successful, `Failure` with an error message if not.
+     */
+    static contextTokenToPartialContext(token, qualifiers) {
+        return ContextTokens.parseContextToken(token, qualifiers).onSuccess((qualifierValues) => {
+            const context = {};
+            for (const { qualifier, value } of qualifierValues) {
+                const qualifierName = qualifier.name;
+                const contextValue = value;
+                // Check for duplicate qualifiers
+                if (qualifierName in context) {
+                    return (0, ts_utils_1.fail)(`${qualifier.name}: duplicate qualifier in context token`);
+                }
+                context[qualifierName] = contextValue;
+            }
+            return (0, ts_utils_1.succeed)(context);
+        });
+    }
+    /**
+     * Converts a validated partial context to a {@link ContextToken | context token}.
+     * @param context - the validated partial context to convert
+     * @returns `Success` with the context token if successful, `Failure` with an error message if not.
+     */
+    static partialContextToContextToken(context) {
+        const tokens = [];
+        for (const [qualifierName, contextValue] of Object.entries(context)) {
+            // Build token as "qualifier=value"
+            tokens.push(`${qualifierName}=${contextValue}`);
+        }
+        if (tokens.length === 0) {
+            return (0, ts_utils_1.succeed)('');
+        }
+        const tokenString = tokens.join('|');
+        // Validate the generated token
+        return common_1.Helpers.buildContextToken(tokens.map((token) => {
+            const [qualifier, value] = token.split('=');
+            return { qualifier, value };
+        })).onSuccess(() => (0, ts_utils_1.succeed)(tokenString));
+    }
+}
+exports.ContextTokens = ContextTokens;
+//# sourceMappingURL=contextToken.js.map

package/lib/packlets/context/contextToken.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contextToken.js","sourceRoot":"","sources":["../../../src/packlets/context/contextToken.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 { mapResults, Result, fail, succeed } from '@fgv/ts-utils';\nimport { Helpers as CommonHelpers, QualifierName, QualifierContextValue } from '../common';\nimport { IValidatedContextQualifierValueDecl, IValidatedContextDecl } from './contextDecls';\nimport { IReadOnlyQualifierCollector, Qualifier } from '../qualifiers';\n\n/**\n * Helper class to parse and validate context tokens.\n * @public\n */\nexport class ContextTokens {\n  /**\n   * The {@link Qualifiers.IReadOnlyQualifierCollector | qualifier collector} used to validate\n   * qualifier names and values.\n   */\n  public readonly qualifiers: IReadOnlyQualifierCollector;\n\n  /**\n   * Constructs a new {@link Context.ContextTokens | ContextTokens } instance.\n   * @param qualifiers - the {@link Qualifiers.IReadOnlyQualifierCollector | qualifier collector} to use\n   */\n  public constructor(qualifiers: IReadOnlyQualifierCollector) {\n    this.qualifiers = qualifiers;\n  }\n\n  /**\n   * Parses a {@link ContextQualifierToken | context qualifier token} string and validates the parts\n   * against the qualifiers present in the {@link Context.ContextTokens.qualifiers | qualifier collector}.\n   * @param token - the token string to parse.\n   * @returns `Success` with the {@link Context.IValidatedContextQualifierValueDecl | validated context qualifier value declaration}\n   * if successful, `Failure` with an error message if not.\n   */\n  public parseContextQualifierToken(token: string): Result<IValidatedContextQualifierValueDecl> {\n    return ContextTokens.parseContextQualifierToken(token, this.qualifiers);\n  }\n\n  /**\n   * Parses a {@link ContextToken | context token} string and validates the parts\n   * against the qualifiers present in the {@link Context.ContextTokens.qualifiers | qualifier collector}.\n   * @param token - the token string to parse.\n   * @returns `Success` with the array of {@link Context.IValidatedContextQualifierValueDecl | validated context qualifier value declarations}\n   * if successful, `Failure` with an error message if not.\n   */\n  public parseContextToken(token: string): Result<IValidatedContextQualifierValueDecl[]> {\n    return ContextTokens.parseContextToken(token, this.qualifiers);\n  }\n\n  /**\n   * Validates the {@link Helpers.IContextTokenParts | parts} of a {@link ContextToken | context token}.\n   * @param parts - the parts to validate\n   * @returns `Success` with the validated declaration if successful, `Failure` with an error message if not.\n   */\n  public validateContextTokenParts(\n    parts: CommonHelpers.IContextTokenParts\n  ): Result<IValidatedContextQualifierValueDecl> {\n    return ContextTokens.validateContextTokenParts(parts, this.qualifiers);\n  }\n\n  /**\n   * Given a value, finds a single token-optional qualifier that matches the value.\n   * Fails if no qualifiers match, or if more than one qualifier matches.\n   * @param value - the value to match.\n   * @returns `Success` with the matching qualifier if successful, `Failure` with an error message if not.\n   */\n  public findQualifierForValue(value: string): Result<Qualifier> {\n    return ContextTokens.findQualifierForValue(value, this.qualifiers);\n  }\n\n  /**\n   * Converts a {@link ContextToken | context token} to a validated partial context.\n   * @param token - the context token to convert\n   * @returns `Success` with the validated partial context if successful, `Failure` with an error message if not.\n   */\n  public contextTokenToPartialContext(token: string): Result<IValidatedContextDecl> {\n    return ContextTokens.contextTokenToPartialContext(token, this.qualifiers);\n  }\n\n  /**\n   * Converts a validated partial context to a {@link ContextToken | context token}.\n   * @param context - the validated partial context to convert\n   * @returns `Success` with the context token if successful, `Failure` with an error message if not.\n   */\n  public partialContextToContextToken(context: IValidatedContextDecl): Result<string> {\n    return ContextTokens.partialContextToContextToken(context);\n  }\n\n  /**\n   * Parses a {@link ContextQualifierToken | context qualifier token} and validates it against the qualifiers\n   * present in the supplied {@link Qualifiers.IReadOnlyQualifierCollector | qualifier collector}.\n   * @param token - the token string to parse.\n   * @param qualifiers - the {@link Qualifiers.IReadOnlyQualifierCollector | qualifier collector} to use\n   * @returns `Success` with a {@link Context.IValidatedContextQualifierValueDecl | validated context qualifier value declaration} if successful,\n   * `Failure` with an error message if not.\n   */\n  public static parseContextQualifierToken(\n    token: string,\n    qualifiers: IReadOnlyQualifierCollector\n  ): Result<IValidatedContextQualifierValueDecl> {\n    return CommonHelpers.parseContextQualifierTokenParts(token).onSuccess((parts) => {\n      return ContextTokens.validateContextTokenParts(parts, qualifiers);\n    });\n  }\n\n  /**\n   * Parses a {@link ContextToken | context token} and validates it against the qualifiers\n   * present in the supplied {@link Qualifiers.IReadOnlyQualifierCollector | qualifier collector}.\n   * @param token - the token string to parse.\n   * @param qualifiers - the {@link Qualifiers.IReadOnlyQualifierCollector | qualifier collector} to use\n   * @returns `Success` with an array of {@link Context.IValidatedContextQualifierValueDecl | validated context qualifier value declarations}\n   * if successful, `Failure` with an error message if not\n   */\n  public static parseContextToken(\n    token: string,\n    qualifiers: IReadOnlyQualifierCollector\n  ): Result<IValidatedContextQualifierValueDecl[]> {\n    return CommonHelpers.parseContextTokenParts(token).onSuccess((parts) => {\n      return mapResults(parts.map((part) => ContextTokens.validateContextTokenParts(part, qualifiers)));\n    });\n  }\n\n  /**\n   * Validates the parts of a context token against the qualifiers present in the supplied\n   * {@link Qualifiers.IReadOnlyQualifierCollector | qualifier collector}.\n   * @param parts - the {@link Helpers.IContextTokenParts | context token parts} to validate.\n   * @param qualifiers - the {@link Qualifiers.IReadOnlyQualifierCollector | qualifier collector} used to\n   * validate qualifier names and values.\n   * @returns `Success` with a {@link Context.IValidatedContextQualifierValueDecl | validated context qualifier value declaration} if successful,\n   * `Failure` with an error message if not.\n   */\n  public static validateContextTokenParts(\n    parts: CommonHelpers.IContextTokenParts,\n    qualifiers: IReadOnlyQualifierCollector\n  ): Result<IValidatedContextQualifierValueDecl> {\n    const qualifierLookup =\n      parts.qualifier === undefined\n        ? ContextTokens.findQualifierForValue(parts.value, qualifiers)\n        : qualifiers.getByNameOrToken(parts.qualifier);\n\n    return qualifierLookup.onSuccess((qualifier) => {\n      return qualifier.type\n        .validateContextValue(parts.value)\n        .onSuccess((value) => {\n          return succeed({ qualifier, value });\n        })\n        .withDetail('failure', 'success');\n    });\n  }\n\n  /**\n   * Given a value and a set of qualifiers, finds a single token-optional qualifier that matches the value.\n   * Fails if no qualifiers match, or if more than one qualifier matches.\n   * @param value - the value to match.\n   * @param qualifiers - the qualifiers to match against.\n   * @returns `Success` with the matching qualifier if successful, `Failure` with an error message if not.\n   */\n  public static findQualifierForValue(\n    value: string,\n    qualifiers: IReadOnlyQualifierCollector\n  ): Result<Qualifier> {\n    const matched: Qualifier[] = [];\n    for (const qualifier of qualifiers.values()) {\n      if (qualifier.tokenIsOptional && qualifier.validateContextValue(value).isSuccess()) {\n        matched.push(qualifier);\n      }\n    }\n    if (matched.length === 0) {\n      return fail(`${value}: does not match any qualifier`);\n    }\n    if (matched.length > 1) {\n      return fail(`${value}: matches multiple qualifiers (${matched.map((q) => q.name).join(', ')})`);\n    }\n    return succeed(matched[0]);\n  }\n\n  /**\n   * Converts a {@link ContextToken | context token} to a validated partial context.\n   * @param token - the context token to convert\n   * @param qualifiers - the {@link Qualifiers.IReadOnlyQualifierCollector | qualifier collector} to use\n   * @returns `Success` with the validated partial context if successful, `Failure` with an error message if not.\n   */\n  public static contextTokenToPartialContext(\n    token: string,\n    qualifiers: IReadOnlyQualifierCollector\n  ): Result<IValidatedContextDecl> {\n    return ContextTokens.parseContextToken(token, qualifiers).onSuccess((qualifierValues) => {\n      const context: IValidatedContextDecl = {};\n\n      for (const { qualifier, value } of qualifierValues) {\n        const qualifierName = qualifier.name as QualifierName;\n        const contextValue = value as QualifierContextValue;\n\n        // Check for duplicate qualifiers\n        if (qualifierName in context) {\n          return fail(`${qualifier.name}: duplicate qualifier in context token`);\n        }\n\n        context[qualifierName] = contextValue;\n      }\n\n      return succeed(context);\n    });\n  }\n\n  /**\n   * Converts a validated partial context to a {@link ContextToken | context token}.\n   * @param context - the validated partial context to convert\n   * @returns `Success` with the context token if successful, `Failure` with an error message if not.\n   */\n  public static partialContextToContextToken(context: IValidatedContextDecl): Result<string> {\n    const tokens: string[] = [];\n\n    for (const [qualifierName, contextValue] of Object.entries(context)) {\n      // Build token as \"qualifier=value\"\n      tokens.push(`${qualifierName}=${contextValue}`);\n    }\n\n    if (tokens.length === 0) {\n      return succeed('');\n    }\n\n    const tokenString = tokens.join('|');\n\n    // Validate the generated token\n    return CommonHelpers.buildContextToken(\n      tokens.map((token) => {\n        const [qualifier, value] = token.split('=');\n        return { qualifier, value };\n      })\n    ).onSuccess(() => succeed(tokenString));\n  }\n}\n"]}