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

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"]}

package/lib/packlets/context/convert/decls.d.ts

@@ -0,0 +1,37 @@
+import { IContextQualifierValueDecl, IValidatedContextDecl, IValidatedContextQualifierValueDecl } from '../contextDecls';
+import { IReadOnlyQualifierCollector } from '../../qualifiers';
+/**
+ * Converter for a {@link Context.IContextQualifierValueDecl | context qualifier value declaration}.
+ * @public
+ */
+export declare const contextQualifierValueDecl: import("@fgv/ts-utils").ObjectConverter<IContextQualifierValueDecl, unknown>;
+/**
+ * Converter for a {@link Context.IContextDecl | context declaration}.
+ * @public
+ */
+export declare const contextDecl: import("@fgv/ts-utils").Converter<Record<string, string>, unknown>;
+/**
+ * Context necessary to convert a {@link Context.IContextQualifierValueDecl | context qualifier value declaration}
+ * or {@link Context.IContextDecl | context declaration} to their
+ * equivalent - {@link Context.IValidatedContextQualifierValueDecl | validated context qualifier value declaration}
+ * or {@link Context.IValidatedContextDecl | validated context declaration}, respectively.
+ * @public
+ */
+export interface IContextDeclConvertContext {
+    readonly qualifiers: IReadOnlyQualifierCollector;
+}
+/**
+ * Converter which constructs a {@link Context.IValidatedContextQualifierValueDecl | validated context qualifier value declaration}
+ * from a {@link Context.IContextQualifierValueDecl | context qualifier value declaration}, instantiating qualifiers by name
+ * from a supplied {@link Context.Convert.IContextDeclConvertContext | conversion context}.
+ * @public
+ */
+export declare const validatedContextQualifierValueDecl: import("@fgv/ts-utils").Converter<IValidatedContextQualifierValueDecl, IContextDeclConvertContext>;
+/**
+ * Converter which constructs a {@link Context.IValidatedContextDecl | validated context declaration}
+ * from a {@link Context.IContextDecl | context declaration}, instantiating qualifiers by name
+ * from a supplied {@link Context.Convert.IContextDeclConvertContext | conversion context}.
+ * @public
+ */
+export declare const validatedContextDecl: import("@fgv/ts-utils").Converter<IValidatedContextDecl, IContextDeclConvertContext>;
+//# sourceMappingURL=decls.d.ts.map

package/lib/packlets/context/convert/decls.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decls.d.ts","sourceRoot":"","sources":["../../../../src/packlets/context/convert/decls.ts"],"names":[],"mappings":"AAuBA,OAAO,EACL,0BAA0B,EAC1B,qBAAqB,EACrB,mCAAmC,EACpC,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,2BAA2B,EAAE,MAAM,kBAAkB,CAAC;AAI/D;;;GAGG;AACH,eAAO,MAAM,yBAAyB,8EAGpC,CAAC;AAEH;;;GAGG;AACH,eAAO,MAAM,WAAW,oEAAyC,CAAC;AAElE;;;;;;GAMG;AACH,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,UAAU,EAAE,2BAA2B,CAAC;CAClD;AAED;;;;;GAKG;AACH,eAAO,MAAM,kCAAkC,oGAyB9C,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,sFA4BhC,CAAC"}

package/lib/packlets/context/convert/decls.js

@@ -0,0 +1,94 @@
+"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.validatedContextDecl = exports.validatedContextQualifierValueDecl = exports.contextDecl = exports.contextQualifierValueDecl = void 0;
+const ts_utils_1 = require("@fgv/ts-utils");
+/* eslint-disable @rushstack/typedef-var */
+/**
+ * Converter for a {@link Context.IContextQualifierValueDecl | context qualifier value declaration}.
+ * @public
+ */
+exports.contextQualifierValueDecl = ts_utils_1.Converters.strictObject({
+    qualifier: ts_utils_1.Converters.string,
+    value: ts_utils_1.Converters.string
+});
+/**
+ * Converter for a {@link Context.IContextDecl | context declaration}.
+ * @public
+ */
+exports.contextDecl = ts_utils_1.Converters.recordOf(ts_utils_1.Converters.string);
+/**
+ * Converter which constructs a {@link Context.IValidatedContextQualifierValueDecl | validated context qualifier value declaration}
+ * from a {@link Context.IContextQualifierValueDecl | context qualifier value declaration}, instantiating qualifiers by name
+ * from a supplied {@link Context.Convert.IContextDeclConvertContext | conversion context}.
+ * @public
+ */
+exports.validatedContextQualifierValueDecl = ts_utils_1.Converters.generic((from, __self, context) => {
+    if (!context) {
+        return ts_utils_1.Failure.with('validatedContextQualifierValueDecl converter requires a context');
+    }
+    return exports.contextQualifierValueDecl.convert(from).onSuccess((decl) => {
+        const { value: qualifier, message } = context.qualifiers.validating.get(decl.qualifier);
+        if (message !== undefined) {
+            return ts_utils_1.Failure.with(message);
+        }
+        return qualifier.validateContextValue(decl.value).onSuccess((value) => {
+            return ts_utils_1.Success.with({
+                qualifier,
+                value
+            });
+        });
+    });
+});
+/**
+ * Converter which constructs a {@link Context.IValidatedContextDecl | validated context declaration}
+ * from a {@link Context.IContextDecl | context declaration}, instantiating qualifiers by name
+ * from a supplied {@link Context.Convert.IContextDeclConvertContext | conversion context}.
+ * @public
+ */
+exports.validatedContextDecl = ts_utils_1.Converters.generic((from, __self, context) => {
+    if (!context) {
+        /* c8 ignore next 2 - functional code path tested but coverage intermittently missed */
+        return ts_utils_1.Failure.with('validatedContextDecl converter requires a context');
+    }
+    return exports.contextDecl.convert(from).onSuccess((decl) => {
+        const errors = new ts_utils_1.MessageAggregator();
+        const result = {};
+        for (const key in decl) {
+            if (key in decl) {
+                const { value: qualifier } = context.qualifiers.validating.get(key).aggregateError(errors);
+                if (qualifier !== undefined) {
+                    qualifier
+                        .validateContextValue(decl[key])
+                        .onSuccess((value) => {
+                        result[qualifier.name] = value;
+                        return (0, ts_utils_1.succeed)(value);
+                    })
+                        .aggregateError(errors);
+                }
+            }
+        }
+        return errors.returnOrReport(ts_utils_1.Success.with(result));
+    });
+});
+//# sourceMappingURL=decls.js.map

package/lib/packlets/context/convert/decls.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"decls.js","sourceRoot":"","sources":["../../../../src/packlets/context/convert/decls.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;;;AAEH,4CAAiG;AAQjG,2CAA2C;AAE3C;;;GAGG;AACU,QAAA,yBAAyB,GAAG,qBAAU,CAAC,YAAY,CAA6B;IAC3F,SAAS,EAAE,qBAAU,CAAC,MAAM;IAC5B,KAAK,EAAE,qBAAU,CAAC,MAAM;CACzB,CAAC,CAAC;AAEH;;;GAGG;AACU,QAAA,WAAW,GAAG,qBAAU,CAAC,QAAQ,CAAC,qBAAU,CAAC,MAAM,CAAC,CAAC;AAalE;;;;;GAKG;AACU,QAAA,kCAAkC,GAAG,qBAAU,CAAC,OAAO,CAIlE,CACE,IAAa,EACb,MAAM,EACN,OAAoC,EACS,EAAE;IAC/C,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,OAAO,kBAAO,CAAC,IAAI,CAAC,iEAAiE,CAAC,CAAC;IACzF,CAAC;IACD,OAAO,iCAAyB,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,SAAS,CAAC,CAAC,IAAI,EAAE,EAAE;QAChE,MAAM,EAAE,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,UAAU,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QACxF,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;YAC1B,OAAO,kBAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QAC/B,CAAC;QACD,OAAO,SAAS,CAAC,oBAAoB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,SAAS,CAAC,CAAC,KAAK,EAAE,EAAE;YACpE,OAAO,kBAAO,CAAC,IAAI,CAAC;gBAClB,SAAS;gBACT,KAAK;aACN,CAAC,CAAC;QACL,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC,CACF,CAAC;AAEF;;;;;GAKG;AACU,QAAA,oBAAoB,GAAG,qBAAU,CAAC,OAAO,CACpD,CAAC,IAAa,EAAE,MAAM,EAAE,OAAoC,EAAiC,EAAE;IAC7F,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,uFAAuF;QACvF,OAAO,kBAAO,CAAC,IAAI,CAAC,mDAAmD,CAAC,CAAC;IAC3E,CAAC;IAED,OAAO,mBAAW,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,SAAS,CAAC,CAAC,IAAI,EAAE,EAAE;QAClD,MAAM,MAAM,GAAG,IAAI,4BAAiB,EAAE,CAAC;QACvC,MAAM,MAAM,GAA0B,EAAE,CAAC;QAEzC,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;YACvB,IAAI,GAAG,IAAI,IAAI,EAAE,CAAC;gBAChB,MAAM,EAAE,KAAK,EAAE,SAAS,EAAE,GAAG,OAAO,CAAC,UAAU,CAAC,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,cAAc,CAAC,MAAM,CAAC,CAAC;gBAC3F,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;oBAC5B,SAAS;yBACN,oBAAoB,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;yBAC/B,SAAS,CAAC,CAAC,KAAK,EAAE,EAAE;wBACnB,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC;wBAC/B,OAAO,IAAA,kBAAO,EAAC,KAAK,CAAC,CAAC;oBACxB,CAAC,CAAC;yBACD,cAAc,CAAC,MAAM,CAAC,CAAC;gBAC5B,CAAC;YACH,CAAC;QACH,CAAC;QACD,OAAO,MAAM,CAAC,cAAc,CAAC,kBAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC;IACrD,CAAC,CAAC,CAAC;AACL,CAAC,CACF,CAAC","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 { Converters, Failure, MessageAggregator, Result, succeed, Success } from '@fgv/ts-utils';\nimport {\n  IContextQualifierValueDecl,\n  IValidatedContextDecl,\n  IValidatedContextQualifierValueDecl\n} from '../contextDecls';\nimport { IReadOnlyQualifierCollector } from '../../qualifiers';\n\n/* eslint-disable @rushstack/typedef-var */\n\n/**\n * Converter for a {@link Context.IContextQualifierValueDecl | context qualifier value declaration}.\n * @public\n */\nexport const contextQualifierValueDecl = Converters.strictObject<IContextQualifierValueDecl>({\n  qualifier: Converters.string,\n  value: Converters.string\n});\n\n/**\n * Converter for a {@link Context.IContextDecl | context declaration}.\n * @public\n */\nexport const contextDecl = Converters.recordOf(Converters.string);\n\n/**\n * Context necessary to convert a {@link Context.IContextQualifierValueDecl | context qualifier value declaration}\n * or {@link Context.IContextDecl | context declaration} to their\n * equivalent - {@link Context.IValidatedContextQualifierValueDecl | validated context qualifier value declaration}\n * or {@link Context.IValidatedContextDecl | validated context declaration}, respectively.\n * @public\n */\nexport interface IContextDeclConvertContext {\n  readonly qualifiers: IReadOnlyQualifierCollector;\n}\n\n/**\n * Converter which constructs a {@link Context.IValidatedContextQualifierValueDecl | validated context qualifier value declaration}\n * from a {@link Context.IContextQualifierValueDecl | context qualifier value declaration}, instantiating qualifiers by name\n * from a supplied {@link Context.Convert.IContextDeclConvertContext | conversion context}.\n * @public\n */\nexport const validatedContextQualifierValueDecl = Converters.generic<\n  IValidatedContextQualifierValueDecl,\n  IContextDeclConvertContext\n>(\n  (\n    from: unknown,\n    __self,\n    context?: IContextDeclConvertContext\n  ): Result<IValidatedContextQualifierValueDecl> => {\n    if (!context) {\n      return Failure.with('validatedContextQualifierValueDecl converter requires a context');\n    }\n    return contextQualifierValueDecl.convert(from).onSuccess((decl) => {\n      const { value: qualifier, message } = context.qualifiers.validating.get(decl.qualifier);\n      if (message !== undefined) {\n        return Failure.with(message);\n      }\n      return qualifier.validateContextValue(decl.value).onSuccess((value) => {\n        return Success.with({\n          qualifier,\n          value\n        });\n      });\n    });\n  }\n);\n\n/**\n * Converter which constructs a {@link Context.IValidatedContextDecl | validated context declaration}\n * from a {@link Context.IContextDecl | context declaration}, instantiating qualifiers by name\n * from a supplied {@link Context.Convert.IContextDeclConvertContext | conversion context}.\n * @public\n */\nexport const validatedContextDecl = Converters.generic<IValidatedContextDecl, IContextDeclConvertContext>(\n  (from: unknown, __self, context?: IContextDeclConvertContext): Result<IValidatedContextDecl> => {\n    if (!context) {\n      /* c8 ignore next 2 - functional code path tested but coverage intermittently missed */\n      return Failure.with('validatedContextDecl converter requires a context');\n    }\n\n    return contextDecl.convert(from).onSuccess((decl) => {\n      const errors = new MessageAggregator();\n      const result: IValidatedContextDecl = {};\n\n      for (const key in decl) {\n        if (key in decl) {\n          const { value: qualifier } = context.qualifiers.validating.get(key).aggregateError(errors);\n          if (qualifier !== undefined) {\n            qualifier\n              .validateContextValue(decl[key])\n              .onSuccess((value) => {\n                result[qualifier.name] = value;\n                return succeed(value);\n              })\n              .aggregateError(errors);\n          }\n        }\n      }\n      return errors.returnOrReport(Success.with(result));\n    });\n  }\n);\n"]}

package/lib/packlets/context/convert/index.d.ts

@@ -0,0 +1,2 @@
+export * from './decls';
+//# sourceMappingURL=index.d.ts.map

package/lib/packlets/context/convert/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/packlets/context/convert/index.ts"],"names":[],"mappings":"AAsBA,cAAc,SAAS,CAAC"}

package/lib/packlets/context/convert/index.js

@@ -0,0 +1,39 @@
+"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 __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./decls"), exports);
+//# sourceMappingURL=index.js.map

package/lib/packlets/context/convert/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/packlets/context/convert/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;;;;;;;;;;;;;;;;AAEH,0CAAwB","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\nexport * from './decls';\n"]}

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

@@ -0,0 +1,5 @@
+import * as Convert from './convert';
+export * from './contextDecls';
+export * from './contextToken';
+export { Convert };
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/packlets/context/index.ts"],"names":[],"mappings":"AAsBA,OAAO,KAAK,OAAO,MAAM,WAAW,CAAC;AACrC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,gBAAgB,CAAC;AAE/B,OAAO,EAAE,OAAO,EAAE,CAAC"}