@fgv/ts-res 5.0.0-30 → 5.0.0-31

package/lib/packlets/runtime/context/contextQualifierProviderValidator.d.ts

@@ -1,18 +1,19 @@
 import { Result } from '@fgv/ts-utils';
 import { QualifierContextValue } from '../../common';
 import { IReadOnlyQualifierCollector } from '../../qualifiers';
-import { IContextQualifierProvider } from './contextQualifierProvider';
+import { IContextQualifierProvider, IReadOnlyContextQualifierProvider, IMutableContextQualifierProvider } from './contextQualifierProvider';
 /**
- * A read-only interface exposing non-mutating methods of a {@link Runtime.Context.ContextQualifierProviderValidator | ContextQualifierProviderValidator}.
+ * Base interface for shared operations between read-only and mutable context qualifier provider validators.
+ * Contains common methods that don't depend on provider mutability.
  * @public
  */
-export interface IReadOnlyContextQualifierProviderValidator {
+export interface IContextQualifierProviderValidatorBase<T extends IContextQualifierProvider = IContextQualifierProvider> {
     /**
-     * {@inheritdoc Runtime.Context.ContextQualifierProviderValidator.provider}
+     * The wrapped context qualifier provider.
      */
-    readonly provider: IContextQualifierProvider;
+    readonly provider: T;
     /**
-     * {@inheritdoc Runtime.Context.ContextQualifierProviderValidator.qualifiers}
+     * The readonly qualifier collector that defines and validates the qualifiers for this context.
      */
     readonly qualifiers: IReadOnlyQualifierCollector;
     /**
@@ -50,6 +51,28 @@ export interface IReadOnlyContextQualifierProviderValidator {
      * or `Failure` with an error message if an error occurs during the check.
      */
     has(name: string): Result<boolean>;
+}
+/**
+ * A read-only interface for validators wrapping read-only context qualifier providers.
+ * Only exposes read operations, providing compile-time type safety by excluding mutation methods.
+ * @public
+ */
+export interface IReadOnlyContextQualifierProviderValidator<T extends IReadOnlyContextQualifierProvider = IReadOnlyContextQualifierProvider> {
+    /**
+     * The wrapped read-only context qualifier provider.
+     */
+    readonly provider: T;
+}
+/**
+ * A mutable interface for validators wrapping mutable context qualifier providers.
+ * Extends the base interface with mutation operations and provides compile-time type safety.
+ * @public
+ */
+export interface IMutableContextQualifierProviderValidator<T extends IMutableContextQualifierProvider = IMutableContextQualifierProvider> extends IContextQualifierProviderValidatorBase<T> {
+    /**
+     * The wrapped mutable context qualifier provider.
+     */
+    readonly provider: T;
     /**
      * Sets a qualifier value using string inputs, converting to strongly-typed values.
      * @param name - The string name to convert.
@@ -67,32 +90,37 @@ export interface IReadOnlyContextQualifierProviderValidator {
     remove(name: string): Result<QualifierContextValue>;
 }
 /**
- * Parameters for constructing a {@link Runtime.Context.ContextQualifierProviderValidator | ContextQualifierProviderValidator}.
+ * Parameters for constructing a read-only context qualifier provider validator.
+ * @public
+ */
+export interface IReadOnlyContextQualifierProviderValidatorCreateParams<T extends IReadOnlyContextQualifierProvider = IReadOnlyContextQualifierProvider> {
+    provider: T;
+}
+/**
+ * Parameters for constructing a mutable context qualifier provider validator.
  * @public
  */
-export interface IContextQualifierProviderValidatorCreateParams {
-    provider: IContextQualifierProvider;
+export interface IMutableContextQualifierProviderValidatorCreateParams<T extends IMutableContextQualifierProvider = IMutableContextQualifierProvider> {
+    provider: T;
 }
 /**
- * A wrapper for {@link Runtime.Context.IContextQualifierProvider | IContextQualifierProvider} that accepts
- * string inputs and converts them to strongly-typed values before calling the wrapped provider.
- * This eliminates the need for type casting in consumer code while maintaining type safety.
+ * Union type for validator constructor parameters.
  * @public
  */
-export declare class ContextQualifierProviderValidator implements IReadOnlyContextQualifierProviderValidator {
+export type IContextQualifierProviderValidatorCreateParams = IReadOnlyContextQualifierProviderValidatorCreateParams | IMutableContextQualifierProviderValidatorCreateParams;
+/**
+ * Base implementation class containing shared validation logic for both read-only and mutable validators.
+ * @internal
+ */
+declare abstract class BaseContextQualifierProviderValidator<T extends IContextQualifierProvider = IContextQualifierProvider> implements IContextQualifierProviderValidatorBase<T> {
     /**
      * The wrapped context qualifier provider.
      */
-    readonly provider: IContextQualifierProvider;
+    abstract readonly provider: T;
     /**
      * The readonly qualifier collector that defines and validates the qualifiers for this context.
      */
     get qualifiers(): IReadOnlyQualifierCollector;
-    /**
-     * Constructs a new {@link Runtime.Context.ContextQualifierProviderValidator | ContextQualifierProviderValidator}.
-     * @param params - Required parameters for constructing the validator.
-     */
-    constructor(params: IContextQualifierProviderValidatorCreateParams);
     /**
      * Gets a qualifier value by its string name, converting to strongly-typed QualifierName.
      * @param name - The string name to convert and look up.
@@ -128,6 +156,40 @@ export declare class ContextQualifierProviderValidator implements IReadOnlyConte
      * or `Failure` with an error message if an error occurs during the check.
      */
     has(name: string): Result<boolean>;
+}
+/**
+ * A validator for read-only context qualifier providers that accepts string inputs
+ * and converts them to strongly-typed values before calling the wrapped provider.
+ * Only provides read operations for compile-time type safety.
+ * @public
+ */
+export declare class ReadOnlyContextQualifierProviderValidator<T extends IReadOnlyContextQualifierProvider = IReadOnlyContextQualifierProvider> extends BaseContextQualifierProviderValidator<T> implements IReadOnlyContextQualifierProviderValidator<T> {
+    /**
+     * The wrapped read-only context qualifier provider.
+     */
+    readonly provider: T;
+    /**
+     * Constructs a new {@link Runtime.Context.ReadOnlyContextQualifierProviderValidator | ReadOnlyContextQualifierProviderValidator}.
+     * @param params - Required parameters for constructing the validator.
+     */
+    constructor(params: IReadOnlyContextQualifierProviderValidatorCreateParams<T>);
+}
+/**
+ * A validator for mutable context qualifier providers that accepts string inputs
+ * and converts them to strongly-typed values before calling the wrapped provider.
+ * Provides both read and mutation operations.
+ * @public
+ */
+export declare class MutableContextQualifierProviderValidator<T extends IMutableContextQualifierProvider = IMutableContextQualifierProvider> extends BaseContextQualifierProviderValidator<T> implements IMutableContextQualifierProviderValidator<T> {
+    /**
+     * The wrapped mutable context qualifier provider.
+     */
+    readonly provider: T;
+    /**
+     * Constructs a new {@link Runtime.Context.MutableContextQualifierProviderValidator | MutableContextQualifierProviderValidator}.
+     * @param params - Required parameters for constructing the validator.
+     */
+    constructor(params: IMutableContextQualifierProviderValidatorCreateParams<T>);
     /**
      * Sets a qualifier value using string inputs, converting to strongly-typed values.
      * @param name - The string name to convert.
@@ -143,23 +205,6 @@ export declare class ContextQualifierProviderValidator implements IReadOnlyConte
      * or `Failure` with an error message if an error occurs.
      */
     remove(name: string): Result<QualifierContextValue>;
-    /**
-     * Validates a string as a QualifierName.
-     * @param name - The string to validate.
-     * @returns `Success` with the strongly-typed QualifierName, or `Failure` if invalid.
-     */
-    private _validateQualifierName;
-    /**
-     * Validates a number as a QualifierIndex.
-     * @param index - The number to validate.
-     * @returns `Success` with the strongly-typed QualifierIndex, or `Failure` if invalid.
-     */
-    private _validateQualifierIndex;
-    /**
-     * Validates a string as a QualifierContextValue.
-     * @param value - The string to validate.
-     * @returns `Success` with the strongly-typed QualifierContextValue, or `Failure` if invalid.
-     */
-    private _validateQualifierContextValue;
 }
+export {};
 //# sourceMappingURL=contextQualifierProviderValidator.d.ts.map

package/lib/packlets/runtime/context/contextQualifierProviderValidator.js

@@ -21,28 +21,20 @@
  * SOFTWARE.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ContextQualifierProviderValidator = void 0;
+exports.MutableContextQualifierProviderValidator = exports.ReadOnlyContextQualifierProviderValidator = void 0;
 const ts_utils_1 = require("@fgv/ts-utils");
+const common_1 = require("../../common");
 /**
- * A wrapper for {@link Runtime.Context.IContextQualifierProvider | IContextQualifierProvider} that accepts
- * string inputs and converts them to strongly-typed values before calling the wrapped provider.
- * This eliminates the need for type casting in consumer code while maintaining type safety.
- * @public
+ * Base implementation class containing shared validation logic for both read-only and mutable validators.
+ * @internal
  */
-class ContextQualifierProviderValidator {
+class BaseContextQualifierProviderValidator {
     /**
      * The readonly qualifier collector that defines and validates the qualifiers for this context.
      */
     get qualifiers() {
         return this.provider.qualifiers;
     }
-    /**
-     * Constructs a new {@link Runtime.Context.ContextQualifierProviderValidator | ContextQualifierProviderValidator}.
-     * @param params - Required parameters for constructing the validator.
-     */
-    constructor(params) {
-        this.provider = params.provider;
-    }
     /**
      * Gets a qualifier value by its string name, converting to strongly-typed QualifierName.
      * @param name - The string name to convert and look up.
@@ -50,7 +42,7 @@ class ContextQualifierProviderValidator {
      * or `Failure` with an error message if not found or an error occurs.
      */
     get(name) {
-        return this._validateQualifierName(name).onSuccess((qualifierName) => {
+        return common_1.Convert.qualifierName.convert(name).onSuccess((qualifierName) => {
             return this.provider.get(qualifierName);
         });
     }
@@ -61,7 +53,7 @@ class ContextQualifierProviderValidator {
      * or `Failure` with an error message if not found or an error occurs.
      */
     getByIndex(index) {
-        return this._validateQualifierIndex(index).onSuccess((qualifierIndex) => {
+        return common_1.Convert.qualifierIndex.convert(index).onSuccess((qualifierIndex) => {
             return this.provider.get(qualifierIndex);
         });
     }
@@ -72,7 +64,7 @@ class ContextQualifierProviderValidator {
      * or `Failure` with an error message if not found, invalid, or an error occurs.
      */
     getValidated(name) {
-        return this._validateQualifierName(name).onSuccess((qualifierName) => {
+        return common_1.Convert.qualifierName.convert(name).onSuccess((qualifierName) => {
             return this.provider.getValidated(qualifierName);
         });
     }
@@ -83,7 +75,7 @@ class ContextQualifierProviderValidator {
      * or `Failure` with an error message if not found, invalid, or an error occurs.
      */
     getValidatedByIndex(index) {
-        return this._validateQualifierIndex(index).onSuccess((qualifierIndex) => {
+        return common_1.Convert.qualifierIndex.convert(index).onSuccess((qualifierIndex) => {
             return this.provider.getValidated(qualifierIndex);
         });
     }
@@ -94,10 +86,43 @@ class ContextQualifierProviderValidator {
      * or `Failure` with an error message if an error occurs during the check.
      */
     has(name) {
-        return this._validateQualifierName(name).onSuccess((qualifierName) => {
+        return common_1.Convert.qualifierName.convert(name).onSuccess((qualifierName) => {
             return this.provider.has(qualifierName);
         });
     }
+}
+/**
+ * A validator for read-only context qualifier providers that accepts string inputs
+ * and converts them to strongly-typed values before calling the wrapped provider.
+ * Only provides read operations for compile-time type safety.
+ * @public
+ */
+class ReadOnlyContextQualifierProviderValidator extends BaseContextQualifierProviderValidator {
+    /**
+     * Constructs a new {@link Runtime.Context.ReadOnlyContextQualifierProviderValidator | ReadOnlyContextQualifierProviderValidator}.
+     * @param params - Required parameters for constructing the validator.
+     */
+    constructor(params) {
+        super();
+        this.provider = params.provider;
+    }
+}
+exports.ReadOnlyContextQualifierProviderValidator = ReadOnlyContextQualifierProviderValidator;
+/**
+ * A validator for mutable context qualifier providers that accepts string inputs
+ * and converts them to strongly-typed values before calling the wrapped provider.
+ * Provides both read and mutation operations.
+ * @public
+ */
+class MutableContextQualifierProviderValidator extends BaseContextQualifierProviderValidator {
+    /**
+     * Constructs a new {@link Runtime.Context.MutableContextQualifierProviderValidator | MutableContextQualifierProviderValidator}.
+     * @param params - Required parameters for constructing the validator.
+     */
+    constructor(params) {
+        super();
+        this.provider = params.provider;
+    }
     /**
      * Sets a qualifier value using string inputs, converting to strongly-typed values.
      * @param name - The string name to convert.
@@ -106,20 +131,9 @@ class ContextQualifierProviderValidator {
      * or `Failure` with an error message if an error occurs.
      */
     set(name, value) {
-        return this._validateQualifierName(name)
-            .onSuccess((qualifierName) => this._validateQualifierContextValue(value))
-            .onSuccess((qualifierValue) => {
-            // Check if the provider has a set method (only available on mutable providers)
-            if ('set' in this.provider && typeof this.provider.set === 'function') {
-                try {
-                    return this.provider.set(name, qualifierValue);
-                }
-                catch (_a) {
-                    return (0, ts_utils_1.fail)(`Provider does not support setting values`);
-                }
-            }
-            return (0, ts_utils_1.fail)(`Provider does not support setting values`);
-        });
+        return common_1.Convert.qualifierName.convert(name).onSuccess((qualifierName) => this.provider.qualifiers.validating.get(name).asResult.onSuccess((qualifier) => ts_utils_1.Converters.string.convert(value).onSuccess((stringValue) => qualifier.validateContextValue(stringValue).onSuccess((qualifierValue) => {
+            return (0, ts_utils_1.captureResult)(() => this.provider.set(qualifierName, qualifierValue)).onSuccess((result) => result);
+        }))));
     }
     /**
      * Removes a qualifier value using string input, converting to strongly-typed QualifierName.
@@ -128,52 +142,10 @@ class ContextQualifierProviderValidator {
      * or `Failure` with an error message if an error occurs.
      */
     remove(name) {
-        return this._validateQualifierName(name).onSuccess((qualifierName) => {
-            // Check if the provider has a remove method (only available on mutable providers)
-            if ('remove' in this.provider && typeof this.provider.remove === 'function') {
-                try {
-                    return this.provider.remove(qualifierName);
-                }
-                catch (_a) {
-                    return (0, ts_utils_1.fail)(`Provider does not support removing values`);
-                }
-            }
-            return (0, ts_utils_1.fail)(`Provider does not support removing values`);
+        return common_1.Convert.qualifierName.convert(name).onSuccess((qualifierName) => {
+            return (0, ts_utils_1.captureResult)(() => this.provider.remove(qualifierName)).onSuccess((result) => result);
         });
     }
-    /**
-     * Validates a string as a QualifierName.
-     * @param name - The string to validate.
-     * @returns `Success` with the strongly-typed QualifierName, or `Failure` if invalid.
-     */
-    _validateQualifierName(name) {
-        if (typeof name !== 'string' || name.length === 0) {
-            return (0, ts_utils_1.fail)(`Invalid qualifier name: "${name}"`);
-        }
-        return (0, ts_utils_1.succeed)(name);
-    }
-    /**
-     * Validates a number as a QualifierIndex.
-     * @param index - The number to validate.
-     * @returns `Success` with the strongly-typed QualifierIndex, or `Failure` if invalid.
-     */
-    _validateQualifierIndex(index) {
-        if (typeof index !== 'number' || !Number.isInteger(index) || index < 0) {
-            return (0, ts_utils_1.fail)(`Invalid qualifier index: ${index}`);
-        }
-        return (0, ts_utils_1.succeed)(index);
-    }
-    /**
-     * Validates a string as a QualifierContextValue.
-     * @param value - The string to validate.
-     * @returns `Success` with the strongly-typed QualifierContextValue, or `Failure` if invalid.
-     */
-    _validateQualifierContextValue(value) {
-        if (typeof value !== 'string') {
-            return (0, ts_utils_1.fail)(`Invalid qualifier context value: "${value}"`);
-        }
-        return (0, ts_utils_1.succeed)(value);
-    }
 }
-exports.ContextQualifierProviderValidator = ContextQualifierProviderValidator;
+exports.MutableContextQualifierProviderValidator = MutableContextQualifierProviderValidator;
 //# sourceMappingURL=contextQualifierProviderValidator.js.map

package/lib/packlets/runtime/context/simpleContextQualifierProvider.d.ts

@@ -1,7 +1,7 @@
 import { Result } from '@fgv/ts-utils';
 import { QualifierName, QualifierContextValue, QualifierIndex } from '../../common';
 import { IReadOnlyQualifierCollector, Qualifier } from '../../qualifiers';
-import { ContextQualifierProvider } from './contextQualifierProvider';
+import { ContextQualifierProvider, IMutableContextQualifierProvider } from './contextQualifierProvider';
 /**
  * Parameters for creating a {@link Runtime.SimpleContextQualifierProvider | SimpleContextQualifierProvider}.
  * @public
@@ -21,7 +21,12 @@ export interface ISimpleContextQualifierProviderCreateParams {
  * using a `ResultMap` for qualifier value storage.
  * @public
  */
-export declare class SimpleContextQualifierProvider extends ContextQualifierProvider {
+export declare class SimpleContextQualifierProvider extends ContextQualifierProvider implements IMutableContextQualifierProvider {
+    /**
+     * Explicit mutability marker for compile-time type discrimination.
+     * Always `true` for mutable providers.
+     */
+    readonly mutable: true;
     /**
      * The readonly qualifier collector that defines and validates the qualifiers for this context.
      */
@@ -99,6 +104,14 @@ export declare class SimpleContextQualifierProvider extends ContextQualifierProv
      * @public
      */
     clear(): void;
+    /**
+     * Resolves a qualifier from a name, index, or qualifier object.
+     * @param nameOrIndexOrQualifier - The input to resolve.
+     * @returns `Success` with the {@link Qualifier | qualifier} if successful,
+     * or `Failure` with an error message if not found or invalid.
+     * @internal
+     */
+    private _resolveQualifier;
     /**
      * Resolves a qualifier name from a name, index, or qualifier object.
      * @param nameOrIndexOrQualifier - The input to resolve.
@@ -107,5 +120,13 @@ export declare class SimpleContextQualifierProvider extends ContextQualifierProv
      * @internal
      */
     private _resolveQualifierName;
+    /**
+     * Resolves a qualifier name from a qualifier-like object.
+     * @param nameOrIndexOrQualifier - The input to resolve.
+     * @returns `Success` with the {@link QualifierName | qualifier name} if successful,
+     * or `Failure` with an error message if not found or invalid.
+     * @internal
+     */
+    private static _qualifierNameFromQualifierLike;
 }
 //# sourceMappingURL=simpleContextQualifierProvider.d.ts.map

package/lib/packlets/runtime/context/simpleContextQualifierProvider.js

@@ -24,6 +24,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.SimpleContextQualifierProvider = void 0;
 const ts_utils_1 = require("@fgv/ts-utils");
 const common_1 = require("../../common");
+const qualifiers_1 = require("../../qualifiers");
 const contextQualifierProvider_1 = require("./contextQualifierProvider");
 /**
  * Simple concrete implementation of {@link Runtime.Context.IContextQualifierProvider | IContextQualifierProvider}
@@ -37,6 +38,11 @@ class SimpleContextQualifierProvider extends contextQualifierProvider_1.ContextQ
      */
     constructor(params) {
         super();
+        /**
+         * Explicit mutability marker for compile-time type discrimination.
+         * Always `true` for mutable providers.
+         */
+        this.mutable = true;
         this.qualifiers = params.qualifiers;
         this._qualifierValues = new ts_utils_1.ResultMap();
         if (params.qualifierValues) {
@@ -63,12 +69,9 @@ class SimpleContextQualifierProvider extends contextQualifierProvider_1.ContextQ
      * or `Failure` with an error message if not found or an error occurs.
      */
     get(nameOrIndexOrQualifier) {
-        const qualifierName = this._resolveQualifierName(nameOrIndexOrQualifier);
-        /* c8 ignore next 3 - functional code path tested but coverage intermittently missed */
-        if (qualifierName.isFailure()) {
-            return (0, ts_utils_1.fail)(qualifierName.message);
-        }
-        return this._qualifierValues.get(qualifierName.value);
+        return this._resolveQualifierName(nameOrIndexOrQualifier).onSuccess((qualifierName) => {
+            return this._qualifierValues.get(qualifierName);
+        });
     }
     /**
      * Gets a validated qualifier context value by its name, index, or qualifier object.
@@ -78,12 +81,11 @@ class SimpleContextQualifierProvider extends contextQualifierProvider_1.ContextQ
      * or `Failure` with an error message if not found, invalid, or an error occurs.
      */
     getValidated(nameOrIndexOrQualifier) {
-        const qualifierName = this._resolveQualifierName(nameOrIndexOrQualifier);
-        if (qualifierName.isFailure()) {
-            return (0, ts_utils_1.fail)(qualifierName.message);
-        }
-        // TODO: Implement validation logic
-        return (0, ts_utils_1.fail)(`getValidated not yet implemented for qualifier "${qualifierName.value}"`);
+        return this._resolveQualifier(nameOrIndexOrQualifier).onSuccess((qualifier) => {
+            return this._qualifierValues.get(qualifier.name).asResult.onSuccess((value) => {
+                return qualifier.validateContextValue(value);
+            });
+        });
     }
     /**
      * Checks if a qualifier value exists with the given name.
@@ -143,34 +145,54 @@ class SimpleContextQualifierProvider extends contextQualifierProvider_1.ContextQ
         this._qualifierValues.clear();
     }
     /**
-     * Resolves a qualifier name from a name, index, or qualifier object.
+     * Resolves a qualifier from a name, index, or qualifier object.
      * @param nameOrIndexOrQualifier - The input to resolve.
-     * @returns `Success` with the {@link QualifierName | qualifier name} if successful,
+     * @returns `Success` with the {@link Qualifier | qualifier} if successful,
      * or `Failure` with an error message if not found or invalid.
      * @internal
      */
-    _resolveQualifierName(nameOrIndexOrQualifier) {
-        // If it's already a QualifierName (string type with brand)
-        if (typeof nameOrIndexOrQualifier === 'string') {
-            /* c8 ignore next 1 - functional code path tested but coverage intermittently missed */
+    _resolveQualifier(nameOrIndexOrQualifier) {
+        if (nameOrIndexOrQualifier instanceof qualifiers_1.Qualifier) {
             return (0, ts_utils_1.succeed)(nameOrIndexOrQualifier);
         }
-        // If it's a Qualifier object
-        if (typeof nameOrIndexOrQualifier === 'object' &&
-            nameOrIndexOrQualifier !== null &&
-            'name' in nameOrIndexOrQualifier) {
-            return (0, ts_utils_1.succeed)(nameOrIndexOrQualifier.name);
+        if (typeof nameOrIndexOrQualifier === 'string') {
+            return this.qualifiers.validating
+                .get(nameOrIndexOrQualifier)
+                .withErrorFormat((error) => `${nameOrIndexOrQualifier}: Not a valid qualifier name.`);
         }
-        // If it's a QualifierIndex (number type with brand)
-        /* c8 ignore next 8 - functional code path tested but coverage intermittently missed */
         if (typeof nameOrIndexOrQualifier === 'number') {
-            const qualifier = this.qualifiers.getAt(nameOrIndexOrQualifier);
-            if (qualifier.isSuccess()) {
-                return (0, ts_utils_1.succeed)(qualifier.value.name);
-            }
-            return (0, ts_utils_1.fail)(`Qualifier not found at index ${nameOrIndexOrQualifier}`);
+            return this.qualifiers
+                .getAt(nameOrIndexOrQualifier)
+                .withErrorFormat((error) => `${nameOrIndexOrQualifier}: Not a valid qualifier index.`);
         }
-        return (0, ts_utils_1.fail)(`Invalid qualifier parameter: ${nameOrIndexOrQualifier}`);
+        return SimpleContextQualifierProvider._qualifierNameFromQualifierLike(nameOrIndexOrQualifier)
+            .onSuccess((qualifierName) => this.qualifiers.validating.get(qualifierName))
+            .withErrorFormat((error) => `${nameOrIndexOrQualifier}: Not a valid Qualifier, name or index.`);
+    }
+    /**
+     * Resolves a qualifier name from a name, index, or qualifier object.
+     * @param nameOrIndexOrQualifier - The input to resolve.
+     * @returns `Success` with the {@link QualifierName | qualifier name} if successful,
+     * or `Failure` with an error message if not found or invalid.
+     * @internal
+     */
+    _resolveQualifierName(nameOrIndexOrQualifier) {
+        return this._resolveQualifier(nameOrIndexOrQualifier).onSuccess((qualifier) => (0, ts_utils_1.succeed)(qualifier.name));
+    }
+    /**
+     * Resolves a qualifier name from a qualifier-like object.
+     * @param nameOrIndexOrQualifier - The input to resolve.
+     * @returns `Success` with the {@link QualifierName | qualifier name} if successful,
+     * or `Failure` with an error message if not found or invalid.
+     * @internal
+     */
+    static _qualifierNameFromQualifierLike(nameOrIndexOrQualifier) {
+        return ts_utils_1.Converters.isA('Qualifier-like object', (v) => typeof v === 'object' &&
+            v !== null &&
+            'name' in v &&
+            typeof v.name === 'string')
+            .map((v) => common_1.Convert.qualifierName.convert(v.name))
+            .convert(nameOrIndexOrQualifier);
     }
 }
 exports.SimpleContextQualifierProvider = SimpleContextQualifierProvider;

package/lib/packlets/runtime/context/validatingSimpleContextQualifierProvider.d.ts

@@ -1,7 +1,7 @@
 import { Result } from '@fgv/ts-utils';
 import { IReadOnlyQualifierCollector } from '../../qualifiers';
 import { SimpleContextQualifierProvider } from './simpleContextQualifierProvider';
-import { IReadOnlyContextQualifierProviderValidator } from './contextQualifierProviderValidator';
+import { IMutableContextQualifierProviderValidator } from './contextQualifierProviderValidator';
 /**
  * Parameters for creating a {@link Runtime.ValidatingSimpleContextQualifierProvider | ValidatingSimpleContextQualifierProvider}.
  * @public
@@ -19,17 +19,17 @@ export interface IValidatingSimpleContextQualifierProviderCreateParams {
 }
 /**
  * A {@link Runtime.SimpleContextQualifierProvider | SimpleContextQualifierProvider} with a
- * {@link Runtime.Context.ContextQualifierProviderValidator | validator} property that enables
+ * {@link Runtime.Context.MutableContextQualifierProviderValidator | validator} property that enables
  * validated use of the underlying provider with string keys and values.
  * This eliminates the need for type casting in consumer code.
  * @public
  */
 export declare class ValidatingSimpleContextQualifierProvider extends SimpleContextQualifierProvider {
     /**
-     * A {@link Runtime.Context.ContextQualifierProviderValidator | ContextQualifierProviderValidator} which validates
+     * A {@link Runtime.Context.MutableContextQualifierProviderValidator | MutableContextQualifierProviderValidator} which validates
      * string inputs before passing them to this provider.
      */
-    readonly validating: IReadOnlyContextQualifierProviderValidator;
+    readonly validating: IMutableContextQualifierProviderValidator;
     /**
      * Constructor for a {@link Runtime.ValidatingSimpleContextQualifierProvider | ValidatingSimpleContextQualifierProvider} object.
      * @param params - {@link Runtime.IValidatingSimpleContextQualifierProviderCreateParams | Parameters} used to create the provider.

package/lib/packlets/runtime/context/validatingSimpleContextQualifierProvider.js

@@ -27,7 +27,7 @@ const simpleContextQualifierProvider_1 = require("./simpleContextQualifierProvid
 const contextQualifierProviderValidator_1 = require("./contextQualifierProviderValidator");
 /**
  * A {@link Runtime.SimpleContextQualifierProvider | SimpleContextQualifierProvider} with a
- * {@link Runtime.Context.ContextQualifierProviderValidator | validator} property that enables
+ * {@link Runtime.Context.MutableContextQualifierProviderValidator | validator} property that enables
  * validated use of the underlying provider with string keys and values.
  * This eliminates the need for type casting in consumer code.
  * @public
@@ -47,7 +47,7 @@ class ValidatingSimpleContextQualifierProvider extends simpleContextQualifierPro
             qualifiers: params.qualifiers,
             qualifierValues: convertedValues
         });
-        this.validating = new contextQualifierProviderValidator_1.ContextQualifierProviderValidator({ provider: this });
+        this.validating = new contextQualifierProviderValidator_1.MutableContextQualifierProviderValidator({ provider: this });
     }
     /**
      * Creates a new {@link Runtime.ValidatingSimpleContextQualifierProvider | ValidatingSimpleContextQualifierProvider} object.

package/lib/packlets/runtime/resourceResolver.js

@@ -191,6 +191,7 @@ class ResourceResolver {
                     return (0, ts_utils_1.fail)(`${conditionSetIndex}: error creating condition set resolution result: ${err}`);
                 });
             }
+            /* c8 ignore next 3 - edge case: matchAsDefault fallback logic rarely triggered */
             if (conditionResult.matchType === 'matchAsDefault') {
                 matchType = 'matchAsDefault';
             }
@@ -252,6 +253,7 @@ class ResourceResolver {
                 });
             }
             else if (resolution.matchType === 'matchAsDefault') {
+                /* c8 ignore next 4 - edge case: default matching instances rarely used in practice */
                 matchingDefaultInstanceResults.push({
                     index: instanceIndex,
                     result: resolution
@@ -276,6 +278,7 @@ class ResourceResolver {
         return (0, ts_utils_1.succeed)(successResult);
     }
     resolveResource(idOrResource) {
+        /* c8 ignore next 4 - defensive coding: string resource resolution should use direct resource calls */
         if (typeof idOrResource === 'string') {
             return this.resourceManager
                 .getBuiltResource(idOrResource)
@@ -307,6 +310,7 @@ class ResourceResolver {
         return (0, ts_utils_1.succeed)(bestCandidate);
     }
     resolveAllResourceCandidates(idOrResource) {
+        /* c8 ignore next 4 - defensive coding: string resource resolution should use direct resource calls */
         if (typeof idOrResource === 'string') {
             return this.resourceManager
                 .getBuiltResource(idOrResource)
@@ -349,6 +353,7 @@ class ResourceResolver {
         return (0, ts_utils_1.succeed)(candidates);
     }
     resolveComposedResourceValue(idOrResource) {
+        /* c8 ignore next 4 - defensive coding: string resource resolution should use direct resource calls */
         if (typeof idOrResource === 'string') {
             return this.resourceManager
                 .getBuiltResource(idOrResource)

package/lib/packlets/zip-archive/types.d.ts

@@ -1,6 +1,6 @@
 import { Model as ConfigModel } from '../config';
 import * as Json from './json';
-import { FileTree } from '@fgv/ts-utils';
+import { FileTree } from '@fgv/ts-json-base';
 /**
  * Options for creating a ZIP archive buffer
  * @public