@fgv/ts-res 5.0.0-2 → 5.0.0-21

package/src/packlets/config/systemConfiguration.ts

@@ -0,0 +1,217 @@
+/*
+ * 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, Result, fail, succeed, omit } from '@fgv/ts-utils';
+import * as QualifierTypes from '../qualifier-types';
+import * as ResourceTypes from '../resource-types';
+import { QualifierType, QualifierTypeCollector, ReadOnlyQualifierTypeCollector } from '../qualifier-types';
+import { IReadOnlyQualifierCollector, QualifierCollector } from '../qualifiers';
+import { ReadOnlyResourceTypeCollector, ResourceType, ResourceTypeCollector } from '../resource-types';
+import { ISystemConfiguration } from './json';
+import { systemConfiguration } from './convert';
+import { JsonFile, sanitizeJsonObject } from '@fgv/ts-json-base';
+import {
+  BuiltInQualifierTypeFactory,
+  BuiltInResourceTypeFactory,
+  IConfigInitFactory
+} from './configInitFactory';
+
+/**
+ * Parameters used to initialize a {@link Config.SystemConfiguration | SystemConfiguration}.
+ * @public
+ */
+export interface ISystemConfigurationInitParams {
+  /**
+   * Optional map of qualifier names to default values. If provided, qualifiers
+   * in the system configuration will be updated with these default values.
+   * Use `null` as the value to remove an existing default value.
+   */
+  qualifierDefaultValues?: Record<string, string | null>; // eslint-disable-line @rushstack/no-new-null
+  qualifierTypeFactory?: IConfigInitFactory<QualifierTypes.Config.IAnyQualifierTypeConfig, QualifierType>;
+  resourceTypeFactory?: IConfigInitFactory<ResourceTypes.Config.IResourceTypeConfig, ResourceType>;
+}
+
+/**
+ * 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: ISystemConfiguration,
+  qualifierDefaultValues: Record<string, string | null> // eslint-disable-line @rushstack/no-new-null
+): Result<ISystemConfiguration> {
+  // Create a copy of the config
+  return sanitizeJsonObject<ISystemConfiguration>(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 = { ...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.
+   */
+  public get name(): string | undefined {
+    return this._config.name;
+  }
+
+  /**
+   * The description of this system configuration.
+   */
+  public get description(): string | undefined {
+    return this._config.description;
+  }
+
+  /**
+   * The {@link QualifierTypes.QualifierTypeCollector | qualifier types} that this system configuration uses.
+   */
+  public readonly qualifierTypes: ReadOnlyQualifierTypeCollector;
+
+  /**
+   * The {@link QualifierTypes.QualifierTypeCollector | qualifier types} that this system configuration uses.
+   * @public
+   */
+  public readonly qualifiers: IReadOnlyQualifierCollector;
+
+  /**
+   * The {@link ResourceTypes.ResourceTypeCollector | resource types} that this system configuration uses.
+   */
+  public readonly resourceTypes: ReadOnlyResourceTypeCollector;
+
+  private readonly _config: ISystemConfiguration;
+
+  /**
+   * 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
+   */
+  protected constructor(config: ISystemConfiguration, initParams?: ISystemConfigurationInitParams) {
+    this._config = config;
+    const qualifierTypeFactory = initParams?.qualifierTypeFactory ?? new BuiltInQualifierTypeFactory();
+    const resourceTypeFactory = initParams?.resourceTypeFactory ?? 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
+   */
+  public static create(
+    config: ISystemConfiguration,
+    initParams?: ISystemConfigurationInitParams
+  ): Result<SystemConfiguration> {
+    if (initParams?.qualifierDefaultValues) {
+      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
+   */
+  public static loadFromFile(
+    path: string,
+    initParams?: ISystemConfigurationInitParams
+  ): Result<SystemConfiguration> {
+    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
+   */
+  public getConfig(): Result<ISystemConfiguration> {
+    return systemConfiguration.convert(this._config);
+  }
+}

package/src/packlets/context/contextDecls.ts

@@ -0,0 +1,76 @@
+/*
+ * 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 { 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>;

package/src/packlets/context/contextToken.ts

@@ -0,0 +1,252 @@
+/*
+ * 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, Result, fail, succeed } from '@fgv/ts-utils';
+import { Helpers as CommonHelpers, QualifierName, QualifierContextValue } from '../common';
+import { IValidatedContextQualifierValueDecl, IValidatedContextDecl } from './contextDecls';
+import { IReadOnlyQualifierCollector, Qualifier } from '../qualifiers';
+
+/**
+ * Helper class to parse and validate context tokens.
+ * @public
+ */
+export class ContextTokens {
+  /**
+   * The {@link Qualifiers.IReadOnlyQualifierCollector | qualifier collector} used to validate
+   * qualifier names and values.
+   */
+  public readonly qualifiers: IReadOnlyQualifierCollector;
+
+  /**
+   * Constructs a new {@link Context.ContextTokens | ContextTokens } instance.
+   * @param qualifiers - the {@link Qualifiers.IReadOnlyQualifierCollector | qualifier collector} to use
+   */
+  public constructor(qualifiers: IReadOnlyQualifierCollector) {
+    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.
+   */
+  public parseContextQualifierToken(token: string): Result<IValidatedContextQualifierValueDecl> {
+    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.
+   */
+  public parseContextToken(token: string): Result<IValidatedContextQualifierValueDecl[]> {
+    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.
+   */
+  public validateContextTokenParts(
+    parts: CommonHelpers.IContextTokenParts
+  ): Result<IValidatedContextQualifierValueDecl> {
+    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.
+   */
+  public findQualifierForValue(value: string): Result<Qualifier> {
+    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.
+   */
+  public contextTokenToPartialContext(token: string): Result<IValidatedContextDecl> {
+    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.
+   */
+  public partialContextToContextToken(context: IValidatedContextDecl): Result<string> {
+    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.
+   */
+  public static parseContextQualifierToken(
+    token: string,
+    qualifiers: IReadOnlyQualifierCollector
+  ): Result<IValidatedContextQualifierValueDecl> {
+    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
+   */
+  public static parseContextToken(
+    token: string,
+    qualifiers: IReadOnlyQualifierCollector
+  ): Result<IValidatedContextQualifierValueDecl[]> {
+    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.
+   */
+  public static validateContextTokenParts(
+    parts: CommonHelpers.IContextTokenParts,
+    qualifiers: IReadOnlyQualifierCollector
+  ): Result<IValidatedContextQualifierValueDecl> {
+    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.
+   */
+  public static findQualifierForValue(
+    value: string,
+    qualifiers: IReadOnlyQualifierCollector
+  ): Result<Qualifier> {
+    const matched: Qualifier[] = [];
+    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.
+   */
+  public static contextTokenToPartialContext(
+    token: string,
+    qualifiers: IReadOnlyQualifierCollector
+  ): Result<IValidatedContextDecl> {
+    return ContextTokens.parseContextToken(token, qualifiers).onSuccess((qualifierValues) => {
+      const context: IValidatedContextDecl = {};
+
+      for (const { qualifier, value } of qualifierValues) {
+        const qualifierName = qualifier.name as QualifierName;
+        const contextValue = value as QualifierContextValue;
+
+        // 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.
+   */
+  public static partialContextToContextToken(context: IValidatedContextDecl): Result<string> {
+    const tokens: string[] = [];
+
+    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));
+  }
+}

package/src/packlets/context/convert/decls.ts

@@ -0,0 +1,126 @@
+/*
+ * 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, Result, succeed, Success } from '@fgv/ts-utils';
+import {
+  IContextQualifierValueDecl,
+  IValidatedContextDecl,
+  IValidatedContextQualifierValueDecl
+} from '../contextDecls';
+import { IReadOnlyQualifierCollector } from '../../qualifiers';
+
+/* eslint-disable @rushstack/typedef-var */
+
+/**
+ * Converter for a {@link Context.IContextQualifierValueDecl | context qualifier value declaration}.
+ * @public
+ */
+export const contextQualifierValueDecl = Converters.strictObject<IContextQualifierValueDecl>({
+  qualifier: Converters.string,
+  value: Converters.string
+});
+
+/**
+ * Converter for a {@link Context.IContextDecl | context declaration}.
+ * @public
+ */
+export const contextDecl = Converters.recordOf(Converters.string);
+
+/**
+ * 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 const validatedContextQualifierValueDecl = Converters.generic<
+  IValidatedContextQualifierValueDecl,
+  IContextDeclConvertContext
+>(
+  (
+    from: unknown,
+    __self,
+    context?: IContextDeclConvertContext
+  ): Result<IValidatedContextQualifierValueDecl> => {
+    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<IValidatedContextDecl, IContextDeclConvertContext>(
+  (from: unknown, __self, context?: IContextDeclConvertContext): Result<IValidatedContextDecl> => {
+    if (!context) {
+      /* c8 ignore next 2 - functional code path tested but coverage intermittently missed */
+      return Failure.with('validatedContextDecl converter requires a context');
+    }
+
+    return contextDecl.convert(from).onSuccess((decl) => {
+      const errors = new MessageAggregator();
+      const result: IValidatedContextDecl = {};
+
+      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));
+    });
+  }
+);