@fgv/ts-res 5.0.1-8 → 5.0.1

package/dist/packlets/config/predefined/extended.js

@@ -0,0 +1,190 @@
+/*
+ * 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.
+ */
+/**
+ * Example extended qualifier types.
+ * @public
+ */
+export const ExtendedQualifierTypes = [
+    {
+        name: 'language',
+        systemType: 'language',
+        configuration: {
+            allowContextList: true
+        }
+    },
+    {
+        name: 'territory',
+        systemType: 'territory',
+        configuration: {
+            allowContextList: false,
+            acceptLowercase: false
+        }
+    },
+    {
+        name: 'role',
+        systemType: 'literal',
+        configuration: {
+            enumeratedValues: ['admin', 'agent', 'user', 'guest']
+        }
+    },
+    {
+        name: 'environment',
+        systemType: 'literal',
+        configuration: {
+            enumeratedValues: ['production', 'integration', 'development', 'test', 'ephemeral']
+        }
+    },
+    {
+        name: 'currency',
+        systemType: 'literal',
+        configuration: {
+            caseSensitive: true,
+            enumeratedValues: ['USD', 'EUR', 'GBP', 'JPY', 'CNY']
+        }
+    },
+    {
+        name: 'market',
+        systemType: 'literal',
+        configuration: {
+            enumeratedValues: [
+                'world',
+                'americas',
+                'europe',
+                'asia',
+                'oceania',
+                'africa',
+                'middle-east',
+                'latin-america',
+                'caribbean',
+                'central-america',
+                'south-america',
+                'north-america',
+                'nordics',
+                'baltic',
+                'balkans',
+                'eastern-europe',
+                'western-europe',
+                'central-europe',
+                'eastern-africa',
+                'western-africa',
+                'central-africa',
+                'north-africa',
+                'south-africa',
+                'middle-africa',
+                'southeast-asia'
+            ],
+            hierarchy: {
+                americas: 'world',
+                europe: 'world',
+                asia: 'world',
+                oceania: 'world',
+                africa: 'world',
+                'middle-east': 'world',
+                'latin-america': 'americas',
+                caribbean: 'americas',
+                'central-america': 'americas',
+                'south-america': 'americas',
+                'north-america': 'americas',
+                nordics: 'europe',
+                baltic: 'europe',
+                balkans: 'europe',
+                'eastern-europe': 'europe',
+                'western-europe': 'europe',
+                'central-europe': 'europe',
+                'eastern-africa': 'africa',
+                'western-africa': 'africa',
+                'central-africa': 'africa',
+                'north-africa': 'africa',
+                'south-africa': 'africa',
+                'middle-africa': 'africa',
+                'southeast-asia': 'asia'
+            }
+        }
+    }
+];
+/**
+ * Example extended qualifiers.
+ * @public
+ */
+export const ExtendedQualifiers = [
+    {
+        name: 'homeTerritory',
+        token: 'home',
+        typeName: 'territory',
+        defaultPriority: 900
+    },
+    {
+        name: 'currentTerritory',
+        token: 'geo',
+        typeName: 'territory',
+        defaultPriority: 850
+    },
+    {
+        name: 'language',
+        token: 'lang',
+        typeName: 'language',
+        defaultPriority: 800
+    },
+    {
+        name: 'market',
+        typeName: 'market',
+        defaultPriority: 750
+    },
+    {
+        name: 'role',
+        typeName: 'role',
+        defaultPriority: 700
+    },
+    {
+        name: 'environment',
+        token: 'env',
+        typeName: 'environment',
+        defaultPriority: 650
+    },
+    {
+        name: 'currency',
+        typeName: 'currency',
+        defaultPriority: 600
+    }
+];
+/**
+ * Example resource types.
+ * @public
+ */
+export const ExtendedResourceTypes = [
+    {
+        name: 'json',
+        typeName: 'json'
+    }
+];
+/**
+ * An example system configuration demonstrating various configuration options.
+ * @public
+ */
+export const ExtendedSystemConfiguration = {
+    name: 'extended-example',
+    description: 'An example system configuration demonstrating various configuration options',
+    qualifierTypes: [...ExtendedQualifierTypes],
+    qualifiers: [...ExtendedQualifiers],
+    resourceTypes: [...ExtendedResourceTypes]
+};
+//# sourceMappingURL=extended.js.map

package/dist/packlets/config/predefined/index.js

@@ -0,0 +1,25 @@
+/*
+ * Copyright (c) 2025 Erik Fortune
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+import * as Default from './default';
+import * as Example from './extended';
+export { Default, Example };
+//# sourceMappingURL=index.js.map

package/dist/packlets/config/systemConfiguration.js

@@ -0,0 +1,147 @@
+/*
+ * Copyright (c) 2025 Erik Fortune
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+import { captureResult, mapResults, fail, succeed, omit } from '@fgv/ts-utils';
+import { QualifierTypeCollector } from '../qualifier-types';
+import { QualifierCollector } from '../qualifiers';
+import { ResourceTypeCollector } from '../resource-types';
+import { systemConfiguration } from './convert';
+import { JsonFile, sanitizeJsonObject } from '@fgv/ts-json-base';
+import { BuiltInQualifierTypeFactory, BuiltInResourceTypeFactory } from './configInitFactory';
+/**
+ * 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
+ */
+export function updateSystemConfigurationQualifierDefaultValues(config, qualifierDefaultValues // eslint-disable-line @rushstack/no-new-null
+) {
+    // Create a copy of the config
+    return 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 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 succeed(updatedConfig);
+    });
+}
+/**
+ * A system configuration for both runtime or build.
+ * @public
+ */
+export 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, initParams) {
+        var _a, _b;
+        this._config = config;
+        const qualifierTypeFactory = (_a = initParams === null || initParams === void 0 ? void 0 : initParams.qualifierTypeFactory) !== null && _a !== void 0 ? _a : new BuiltInQualifierTypeFactory();
+        const resourceTypeFactory = (_b = initParams === null || initParams === void 0 ? void 0 : initParams.resourceTypeFactory) !== null && _b !== void 0 ? _b : new BuiltInResourceTypeFactory();
+        this.qualifierTypes = QualifierTypeCollector.create({
+            qualifierTypes: mapResults(config.qualifierTypes.map((tc) => qualifierTypeFactory.create(tc))).orThrow()
+        }).orThrow();
+        this.qualifiers = QualifierCollector.create({
+            qualifierTypes: this.qualifierTypes,
+            qualifiers: config.qualifiers
+        }).orThrow();
+        this.resourceTypes = ResourceTypeCollector.create({
+            resourceTypes: mapResults(config.resourceTypes.map((rt) => resourceTypeFactory.create(rt))).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) {
+            /* c8 ignore next 9 - functional code tested but coverage intermittently missed */
+            return updateSystemConfigurationQualifierDefaultValues(config, initParams.qualifierDefaultValues).onSuccess((updatedConfig) => captureResult(() => new SystemConfiguration(updatedConfig, omit(initParams, ['qualifierDefaultValues']))));
+        }
+        return captureResult(() => new SystemConfiguration(config, initParams));
+    }
+    /**
+     * Loads a {@link Config.SystemConfiguration | SystemConfiguration} from a file.
+     * @param path - The path to the file to load.
+     * @returns `Success` with the {@link Config.SystemConfiguration | SystemConfiguration}
+     * if successful, `Failure` with an error message otherwise.
+     * @public
+     */
+    static loadFromFile(path, initParams) {
+        return JsonFile.convertJsonFileSync(path, systemConfiguration).onSuccess((config) => SystemConfiguration.create(config, initParams));
+    }
+    /**
+     * 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 systemConfiguration.convert(this._config);
+    }
+}
+//# sourceMappingURL=systemConfiguration.js.map

package/dist/packlets/context/contextDecls.js

@@ -0,0 +1,23 @@
+/*
+ * 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.
+ */
+export {};
+//# sourceMappingURL=contextDecls.js.map

package/dist/packlets/context/contextToken.js

@@ -0,0 +1,202 @@
+/*
+ * Copyright (c) 2025 Erik Fortune
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+import { mapResults, fail, succeed } from '@fgv/ts-utils';
+import { Helpers as CommonHelpers } from '../common';
+/**
+ * Helper class to parse and validate context tokens.
+ * @public
+ */
+export 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 CommonHelpers.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 CommonHelpers.parseContextTokenParts(token).onSuccess((parts) => {
+            return 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 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 fail(`${value}: does not match any qualifier`);
+        }
+        if (matched.length > 1) {
+            return fail(`${value}: matches multiple qualifiers (${matched.map((q) => q.name).join(', ')})`);
+        }
+        return 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 fail(`${qualifier.name}: duplicate qualifier in context token`);
+                }
+                context[qualifierName] = contextValue;
+            }
+            return 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 succeed('');
+        }
+        const tokenString = tokens.join('|');
+        // Validate the generated token
+        return CommonHelpers.buildContextToken(tokens.map((token) => {
+            const [qualifier, value] = token.split('=');
+            return { qualifier, value };
+        })).onSuccess(() => succeed(tokenString));
+    }
+}
+//# sourceMappingURL=contextToken.js.map

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

@@ -0,0 +1,91 @@
+/*
+ * Copyright (c) 2025 Erik Fortune
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+import { Converters, Failure, MessageAggregator, succeed, Success } from '@fgv/ts-utils';
+/* eslint-disable @rushstack/typedef-var */
+/**
+ * Converter for a {@link Context.IContextQualifierValueDecl | context qualifier value declaration}.
+ * @public
+ */
+export const contextQualifierValueDecl = Converters.strictObject({
+    qualifier: Converters.string,
+    value: Converters.string
+});
+/**
+ * Converter for a {@link Context.IContextDecl | context declaration}.
+ * @public
+ */
+export const contextDecl = Converters.recordOf(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
+ */
+export const validatedContextQualifierValueDecl = Converters.generic((from, __self, context) => {
+    if (!context) {
+        return Failure.with('validatedContextQualifierValueDecl converter requires a context');
+    }
+    return contextQualifierValueDecl.convert(from).onSuccess((decl) => {
+        const { value: qualifier, message } = context.qualifiers.validating.get(decl.qualifier);
+        if (message !== undefined) {
+            return Failure.with(message);
+        }
+        return qualifier.validateContextValue(decl.value).onSuccess((value) => {
+            return 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
+ */
+export const validatedContextDecl = Converters.generic((from, __self, context) => {
+    /* c8 ignore next 3 - functional code path tested but coverage intermittently missed */
+    if (!context) {
+        return Failure.with('validatedContextDecl converter requires a context');
+    }
+    return contextDecl.convert(from).onSuccess((decl) => {
+        const errors = new 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 succeed(value);
+                    })
+                        .aggregateError(errors);
+                }
+            }
+        }
+        return errors.returnOrReport(Success.with(result));
+    });
+});
+//# sourceMappingURL=decls.js.map