@fgv/ts-res 5.0.0-9 → 5.0.1-1

package/dist/tsdoc-metadata.json

@@ -5,7 +5,7 @@
   "toolPackages": [
     {
       "packageName": "@microsoft/api-extractor",
-      "packageVersion": "7.52.8"
+      "packageVersion": "7.52.12"
     }
   ]
 }

package/eslint.config.js

@@ -0,0 +1,16 @@
+// ESLint 9 flat config
+const nodeProfile = require('@rushstack/eslint-config/flat/profile/node');
+const packletsPlugin = require('@rushstack/eslint-config/flat/mixins/packlets');
+const tsdocPlugin = require('@rushstack/eslint-config/flat/mixins/tsdoc');
+
+module.exports = [
+  ...nodeProfile,
+  packletsPlugin,
+  ...tsdocPlugin,
+  {
+    // Override specific rules if needed
+    rules: {
+      '@rushstack/packlets/mechanics': 'warn'
+    }
+  }
+];

package/lib/index.d.ts

@@ -10,6 +10,7 @@ import * as Resources from './packlets/resources';
 import * as ResourceTypes from './packlets/resource-types';
 import * as Import from './packlets/import';
 import * as Runtime from './packlets/runtime';
+import * as ZipArchive from './packlets/zip-archive';
 export * from './packlets/common';
 import { Condition, ConditionSet } from './packlets/conditions';
 import { Decision } from './packlets/decisions';
@@ -19,5 +20,5 @@ import { ResourceType } from './packlets/resource-types';
 import { Resource, ResourceCandidate, ResourceManagerBuilder } from './packlets/resources';
 import { IResourceManager, ResourceResolver } from './packlets/runtime';
 import { BundleBuilder, BundleLoader } from './packlets/bundle';
-export { Bundle, BundleBuilder, BundleLoader, Condition, Conditions, ConditionSet, Config, Context, Decision, Decisions, Import, IResourceManager, Qualifier, QualifierType, QualifierTypes, Qualifiers, Resource, ResourceCandidate, ResourceJson, ResourceResolver, ResourceManagerBuilder, ResourceType, ResourceTypes, Resources, Runtime };
+export { Bundle, BundleBuilder, BundleLoader, Condition, Conditions, ConditionSet, Config, Context, Decision, Decisions, Import, IResourceManager, Qualifier, QualifierType, QualifierTypes, Qualifiers, Resource, ResourceCandidate, ResourceJson, ResourceResolver, ResourceManagerBuilder, ResourceType, ResourceTypes, Resources, Runtime, ZipArchive };
 //# sourceMappingURL=index.d.ts.map

package/lib/index.js

@@ -57,7 +57,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Runtime = exports.Resources = exports.ResourceTypes = exports.ResourceType = exports.ResourceManagerBuilder = exports.ResourceResolver = exports.ResourceJson = exports.ResourceCandidate = exports.Resource = exports.Qualifiers = exports.QualifierTypes = exports.QualifierType = exports.Qualifier = exports.Import = exports.Decisions = exports.Decision = exports.Context = exports.Config = exports.ConditionSet = exports.Conditions = exports.Condition = exports.BundleLoader = exports.BundleBuilder = exports.Bundle = void 0;
+exports.ZipArchive = exports.Runtime = exports.Resources = exports.ResourceTypes = exports.ResourceType = exports.ResourceManagerBuilder = exports.ResourceResolver = exports.ResourceJson = exports.ResourceCandidate = exports.Resource = exports.Qualifiers = exports.QualifierTypes = exports.QualifierType = exports.Qualifier = exports.Import = exports.Decisions = exports.Decision = exports.Context = exports.Config = exports.ConditionSet = exports.Conditions = exports.Condition = exports.BundleLoader = exports.BundleBuilder = exports.Bundle = void 0;
 const Bundle = __importStar(require("./packlets/bundle"));
 exports.Bundle = Bundle;
 const QualifierTypes = __importStar(require("./packlets/qualifier-types"));
@@ -82,6 +82,8 @@ const Import = __importStar(require("./packlets/import"));
 exports.Import = Import;
 const Runtime = __importStar(require("./packlets/runtime"));
 exports.Runtime = Runtime;
+const ZipArchive = __importStar(require("./packlets/zip-archive"));
+exports.ZipArchive = ZipArchive;
 __exportStar(require("./packlets/common"), exports);
 const conditions_1 = require("./packlets/conditions");
 Object.defineProperty(exports, "Condition", { enumerable: true, get: function () { return conditions_1.Condition; } });

package/lib/packlets/bundle/bundleBuilder.js

@@ -42,18 +42,19 @@ class BundleBuilder {
      */
     static create(builder, systemConfig, params) {
         var _a;
-        /* c8 ignore next 1 */
+        /* c8 ignore next 2 - defense in depth */
         params = params !== null && params !== void 0 ? params : {};
         const hashNormalizer = (_a = params.hashNormalizer) !== null && _a !== void 0 ? _a : new ts_utils_1.Hash.Crc32Normalizer();
-        // Determine which builder to use based on normalization setting
-        const builderToUse = params.normalize
+        const builderToUse = params.normalize === true
             ? bundleNormalizer_1.BundleNormalizer.normalize(builder, systemConfig)
-            : (0, ts_utils_1.succeed)(builder);
+            : /* c8 ignore next 1 - is tested but coverage gets confused */
+                (0, ts_utils_1.succeed)(builder);
         return builderToUse.onSuccess((targetBuilder) => {
             return systemConfig.getConfig().onSuccess((config) => {
                 return targetBuilder.getCompiledResourceCollection().onSuccess((compiledCollection) => {
                     return BundleBuilder._generateChecksum(compiledCollection, hashNormalizer).onSuccess((checksum) => {
                         var _a;
+                        /* c8 ignore next 1 - defense in depth */
                         const dateBuilt = (_a = params.dateBuilt) !== null && _a !== void 0 ? _a : new Date().toISOString();
                         const metadata = {
                             dateBuilt,
@@ -96,11 +97,13 @@ class BundleBuilder {
                     return targetBuilder.getCompiledResourceCollection().onSuccess((compiledCollection) => {
                         return BundleBuilder._generateChecksum(compiledCollection, hashNormalizer).onSuccess((checksum) => {
                             var _a;
+                            /* c8 ignore next 1 - defense in depth */
                             const dateBuilt = (_a = params.dateBuilt) !== null && _a !== void 0 ? _a : new Date().toISOString();
                             const metadata = {
                                 dateBuilt,
                                 checksum,
                                 version: params.version,
+                                /* c8 ignore next 1 - defense in depth */
                                 description: params === null || params === void 0 ? void 0 : params.description
                             };
                             const bundle = {

package/lib/packlets/bundle/bundleLoader.js

@@ -39,6 +39,7 @@ class BundleLoader {
      */
     static createManagerFromBundle(params) {
         var _a, _b;
+        /* c8 ignore next 1 - defense in depth */
         const hashNormalizer = (_a = params.hashNormalizer) !== null && _a !== void 0 ? _a : new ts_utils_1.Hash.Crc32Normalizer();
         return BundleLoader._verifyBundleIntegrity(params.bundle, (_b = params.skipChecksumVerification) !== null && _b !== void 0 ? _b : false, hashNormalizer).onSuccess(() => {
             return BundleLoader._createSystemConfiguration(params.bundle).onSuccess((systemConfig) => {

package/lib/packlets/bundle/bundleUtils.js

@@ -49,22 +49,19 @@ class BundleUtils {
      * @public
      */
     static extractBundleComponents(bundleData) {
-        // First validate and convert the bundle
-        const bundleResult = convert_1.bundle.convert(bundleData);
-        if (bundleResult.isFailure()) {
-            return (0, ts_utils_1.fail)(`Invalid bundle structure: ${bundleResult.message}`);
-        }
-        const bundle = bundleResult.value;
-        // Create SystemConfiguration from the bundle config
-        const systemConfigResult = config_1.SystemConfiguration.create(bundle.config);
-        if (systemConfigResult.isFailure()) {
-            return (0, ts_utils_1.fail)(`Invalid system configuration in bundle: ${systemConfigResult.message}`);
-        }
-        const systemConfiguration = systemConfigResult.value;
-        return (0, ts_utils_1.succeed)({
-            systemConfiguration,
-            compiledCollection: bundle.compiledCollection,
-            metadata: bundle.metadata
+        return convert_1.bundle
+            .convert(bundleData)
+            .withErrorFormat((err) => `Invalid bundle structure: ${err}`)
+            .onSuccess((bundle) => {
+            return config_1.SystemConfiguration.create(bundle.config)
+                .withErrorFormat((err) => `Invalid system configuration in bundle: ${err}`)
+                .onSuccess((systemConfiguration) => {
+                return (0, ts_utils_1.succeed)({
+                    systemConfiguration,
+                    compiledCollection: bundle.compiledCollection,
+                    metadata: bundle.metadata
+                });
+            });
         });
     }
     /**
@@ -97,6 +94,7 @@ class BundleUtils {
             return BundleUtils.extractBundleComponents(data);
         }
         catch (error) {
+            /* c8 ignore next 1 - defense in depth */
             return (0, ts_utils_1.fail)(`Failed to parse JSON: ${error instanceof Error ? error.message : String(error)}`);
         }
     }

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

@@ -7,13 +7,15 @@
  *
  * @packageDocumentation
  */
+import * as Model from './model';
+import * as Convert from './convert';
 export type { IBundleMetadata, IBundleExportMetadata, IBundle, IBundleCreateParams } from './model';
 export { BundleBuilder } from './bundleBuilder';
 export { BundleLoader } from './bundleLoader';
 export type { IBundleLoaderCreateParams } from './bundleLoader';
 export { BundleUtils } from './bundleUtils';
 export type { IBundleComponents } from './bundleUtils';
-export * as Convert from './convert';
+export { Model, Convert };
 /** @internal */
 export { BundleNormalizer } from './bundleNormalizer';
 //# sourceMappingURL=index.d.ts.map

package/lib/packlets/bundle/index.js

@@ -54,7 +54,20 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.BundleNormalizer = exports.Convert = exports.BundleUtils = exports.BundleLoader = exports.BundleBuilder = void 0;
+exports.BundleNormalizer = exports.Convert = exports.Model = exports.BundleUtils = exports.BundleLoader = exports.BundleBuilder = void 0;
+/**
+ * Bundle packlet providing functionality for creating and loading resource bundles.
+ *
+ * Resource bundles encapsulate compiled resources, configuration, and metadata with
+ * integrity verification. They provide a portable way to distribute pre-compiled
+ * resource collections.
+ *
+ * @packageDocumentation
+ */
+const Model = __importStar(require("./model"));
+exports.Model = Model;
+const Convert = __importStar(require("./convert"));
+exports.Convert = Convert;
 // Builder and loader classes
 var bundleBuilder_1 = require("./bundleBuilder");
 Object.defineProperty(exports, "BundleBuilder", { enumerable: true, get: function () { return bundleBuilder_1.BundleBuilder; } });
@@ -63,8 +76,6 @@ Object.defineProperty(exports, "BundleLoader", { enumerable: true, get: function
 // Utilities
 var bundleUtils_1 = require("./bundleUtils");
 Object.defineProperty(exports, "BundleUtils", { enumerable: true, get: function () { return bundleUtils_1.BundleUtils; } });
-// Converters
-exports.Convert = __importStar(require("./convert"));
 // Internal utilities (not part of public API)
 /** @internal */
 var bundleNormalizer_1 = require("./bundleNormalizer");

package/lib/packlets/common/convert.d.ts

@@ -18,6 +18,11 @@ export declare const qualifierTypeName: import("@fgv/ts-utils").Converter<import
  * @public
  */
 export declare const qualifierTypeIndex: import("@fgv/ts-utils").Converter<import("./conditions").QualifierTypeIndex, unknown>;
+/**
+ * `Converter` which validates an `unknown` value as a {@link QualifierContextValue | QualifierContextValue}.
+ * @public
+ */
+export declare const qualifierContextValue: import("@fgv/ts-utils").Converter<import("./conditions").QualifierContextValue, unknown>;
 /**
  * `Converter` which validates an `unknown` value as a {@link QualifierConditionValue | QualifierConditionValue}.
  * @public
@@ -103,6 +108,16 @@ export declare const resourceTypeName: import("@fgv/ts-utils").Converter<import(
  * @public
  */
 export declare const resourceTypeIndex: import("@fgv/ts-utils").Converter<import("./resources").ResourceTypeIndex, unknown>;
+/**
+ * `Converter` which validates an `unknown` value as a {@link CandidateValueKey | CandidateValueKey}.
+ * @public
+ */
+export declare const candidateValueKey: import("@fgv/ts-utils").Converter<import("./resources").CandidateValueKey, unknown>;
+/**
+ * `Converter` which validates an `unknown` value as a {@link CandidateValueIndex | CandidateValueIndex}.
+ * @public
+ */
+export declare const candidateValueIndex: import("@fgv/ts-utils").Converter<import("./resources").CandidateValueIndex, unknown>;
 /**
  * `Converter` for a resource value merge method.
  * @public

package/lib/packlets/common/convert.js

@@ -54,7 +54,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.qualifierDefaultValuesToken = exports.qualifierDefaultValueToken = exports.contextToken = exports.contextQualifierToken = exports.resourceValueMergeMethod = exports.resourceTypeIndex = exports.resourceTypeName = exports.resourceIndex = exports.resourceName = exports.resourceId = exports.decisionKey = exports.decisionIndex = exports.conditionSetHash = exports.conditionSetToken = exports.conditionSetKey = exports.conditionSetIndex = exports.conditionToken = exports.conditionKey = exports.conditionIndex = exports.conditionOperator = exports.conditionPriority = exports.qualifierMatchScore = exports.qualifierTypeIndex = exports.qualifierTypeName = exports.qualifierIndex = exports.qualifierName = void 0;
+exports.qualifierDefaultValuesToken = exports.qualifierDefaultValueToken = exports.contextToken = exports.contextQualifierToken = exports.resourceValueMergeMethod = exports.candidateValueIndex = exports.candidateValueKey = exports.resourceTypeIndex = exports.resourceTypeName = exports.resourceIndex = exports.resourceName = exports.resourceId = exports.decisionKey = exports.decisionIndex = exports.conditionSetHash = exports.conditionSetToken = exports.conditionSetKey = exports.conditionSetIndex = exports.conditionToken = exports.conditionKey = exports.conditionIndex = exports.conditionOperator = exports.conditionPriority = exports.qualifierMatchScore = exports.qualifierContextValue = exports.qualifierTypeIndex = exports.qualifierTypeName = exports.qualifierIndex = exports.qualifierName = void 0;
 const ts_utils_1 = require("@fgv/ts-utils");
 const Validate = __importStar(require("./validate"));
 const conditions_1 = require("./conditions");
@@ -80,6 +80,11 @@ exports.qualifierTypeName = ts_utils_1.Converters.string.map(Validate.toQualifie
  * @public
  */
 exports.qualifierTypeIndex = ts_utils_1.Converters.number.map(Validate.toQualifierTypeIndex);
+/**
+ * `Converter` which validates an `unknown` value as a {@link QualifierContextValue | QualifierContextValue}.
+ * @public
+ */
+exports.qualifierContextValue = ts_utils_1.Converters.string.map(Validate.toQualifierContextValue);
 /**
  * `Converter` which validates an `unknown` value as a {@link QualifierConditionValue | QualifierConditionValue}.
  * @public
@@ -165,6 +170,16 @@ exports.resourceTypeName = ts_utils_1.Converters.string.map(Validate.toResourceT
  * @public
  */
 exports.resourceTypeIndex = ts_utils_1.Converters.number.map(Validate.toResourceTypeIndex);
+/**
+ * `Converter` which validates an `unknown` value as a {@link CandidateValueKey | CandidateValueKey}.
+ * @public
+ */
+exports.candidateValueKey = ts_utils_1.Converters.string.map(Validate.toCandidateValueKey);
+/**
+ * `Converter` which validates an `unknown` value as a {@link CandidateValueIndex | CandidateValueIndex}.
+ * @public
+ */
+exports.candidateValueIndex = ts_utils_1.Converters.number.map(Validate.toCandidateValueIndex);
 /**
  * `Converter` for a resource value merge method.
  * @public

package/lib/packlets/common/helpers/context.js

@@ -67,6 +67,7 @@ const Validate = __importStar(require("../validate"));
  * @public
  */
 function buildContextQualifierToken({ qualifier, value }) {
+    /* c8 ignore next 1 - edge case: ternary expression alternate branch rarely hit */
     return Validate.toContextQualifierToken(qualifier ? `${qualifier}=${value}` : value);
 }
 /**

package/lib/packlets/common/helpers/resources.d.ts

@@ -31,4 +31,11 @@ export declare function joinResourceIds(...ids: (string | undefined)[]): Result<
  * @public
  */
 export declare function joinOptionalResourceIds(...ids: (string | undefined)[]): Result<ResourceId | undefined>;
+/**
+ * Gets the name for a resource ID.
+ * @param id - The resource ID to get the name for.
+ * @returns The resource name if found, or undefined if not.
+ * @public
+ */
+export declare function getNameForResourceId(id: string | undefined): Result<ResourceName>;
 //# sourceMappingURL=resources.d.ts.map

package/lib/packlets/common/helpers/resources.js

@@ -24,6 +24,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.splitResourceId = splitResourceId;
 exports.joinResourceIds = joinResourceIds;
 exports.joinOptionalResourceIds = joinOptionalResourceIds;
+exports.getNameForResourceId = getNameForResourceId;
 const ts_utils_1 = require("@fgv/ts-utils");
 const resources_1 = require("../validate/resources");
 /**
@@ -35,6 +36,7 @@ const resources_1 = require("../validate/resources");
  * @public
  */
 function splitResourceId(id) {
+    /* c8 ignore next 3 - edge case: undefined resource ID should not occur in normal operation */
     if (id === undefined) {
         return (0, ts_utils_1.succeed)([]);
     }
@@ -82,4 +84,15 @@ function joinOptionalResourceIds(...ids) {
     const id = parts.join('.');
     return errors.returnOrReport(id ? (0, resources_1.toResourceId)(id) : (0, ts_utils_1.succeed)(undefined));
 }
+/**
+ * Gets the name for a resource ID.
+ * @param id - The resource ID to get the name for.
+ * @returns The resource name if found, or undefined if not.
+ * @public
+ */
+function getNameForResourceId(id) {
+    return splitResourceId(id).onSuccess((parts) => {
+        return parts.length > 0 ? (0, ts_utils_1.succeed)(parts[parts.length - 1]) : fail('Empty id has no name');
+    });
+}
 //# sourceMappingURL=resources.js.map

package/lib/packlets/common/resources.d.ts

@@ -1,4 +1,5 @@
-import { Brand } from '@fgv/ts-utils';
+import { JsonValue } from '@fgv/ts-json-base';
+import { Brand, Result } from '@fgv/ts-utils';
 /**
  * Branded string representing a validated resource id.  A resource ID
  * is a dot-separated sequence of resource names.
@@ -46,4 +47,46 @@ export declare const allResourceValueMergeMethods: ResourceValueMergeMethod[];
  * @public
  */
 export type CandidateCompleteness = 'full' | 'partial';
+/**
+ * Branded number representing a validated candidate value index.
+ * Candidate value indices are used to identify candidate values
+ * within a resource set and to enable sharing of like values.
+ * @public
+ */
+export type CandidateValueIndex = Brand<number, 'CandidateValueIndex'>;
+/**
+ * Branded string representing a validated candidate value key.
+ * Candidate value keys are used to identify candidate values
+ * within a resource set and to enable sharing of like values.
+ * @public
+ */
+export type CandidateValueKey = Brand<string, 'CandidateValueKey'>;
+/**
+ * Minimal resource resolver
+ * @public
+ */
+export interface IResourceResolver {
+    /**
+     * The resource IDs that this resolver can resolve.
+     */
+    readonly resourceIds: ReadonlyArray<ResourceId>;
+    /**
+     * Resolves a resource to a composed value by merging matching candidates according to their merge methods.
+     * Starting from the highest priority candidates, finds the first "full" candidate and merges all higher
+     * priority "partial" candidates into it in ascending order of priority.
+     * @param resource - The string id of the resource to resolve.
+     * @returns `Success` with the composed JsonValue if successful,
+     * or `Failure` with an error message if no candidates match or resolution fails.
+     * @public
+     */
+    resolveComposedResourceValue(resource: string): Result<JsonValue>;
+    /**
+     * Creates a new {@link IResourceResolver | resource resolver} with the given context.
+     * @param context - The context to use for the new resource resolver.
+     * @returns `Success` with the new resource resolver if successful,
+     * or `Failure` with an error message if the context is invalid.
+     * @public
+     */
+    withContext(context: Record<string, string>): Result<IResourceResolver>;
+}
 //# sourceMappingURL=resources.d.ts.map

package/lib/packlets/common/validate/conditions.d.ts

@@ -1,5 +1,5 @@
 import { Result } from '@fgv/ts-utils';
-import { ConditionPriority, QualifierName, QualifierTypeName, QualifierIndex, QualifierTypeIndex, ConditionIndex, ConditionSetIndex, QualifierMatchScore, ConditionKey, ConditionSetKey, DecisionKey, DecisionIndex, ConditionSetHash, ConditionOperator, ConditionToken, ConditionSetToken, ContextQualifierToken, ContextToken, QualifierDefaultValueToken, QualifierDefaultValuesToken } from '../conditions';
+import { ConditionPriority, QualifierName, QualifierTypeName, QualifierIndex, QualifierTypeIndex, ConditionIndex, ConditionSetIndex, QualifierMatchScore, QualifierContextValue, ConditionKey, ConditionSetKey, DecisionKey, DecisionIndex, ConditionSetHash, ConditionOperator, ConditionToken, ConditionSetToken, ContextQualifierToken, ContextToken, QualifierDefaultValueToken, QualifierDefaultValuesToken } from '../conditions';
 /**
  * Determines whether a string is a valid qualifier name.
  * @param name - the string to validate
@@ -117,6 +117,14 @@ export declare function isValidDecisionKey(key: string): key is DecisionKey;
  * @public
  */
 export declare function isValidDecisionIndex(index: number): index is DecisionIndex;
+/**
+ * Determines whether a string is a valid qualifier context value.
+ * For now, any non-empty string is considered a valid context value.
+ * @param value - the string to validate
+ * @returns true if the string is a valid qualifier context value, false otherwise.
+ * @public
+ */
+export declare function isValidQualifierContextValue(value: string): value is QualifierContextValue;
 /**
  * Converts a string to a {@link QualifierName} if it is a valid qualifier name.
  * @param name - the string to convert
@@ -125,6 +133,14 @@ export declare function isValidDecisionIndex(index: number): index is DecisionIn
  * @public
  */
 export declare function toQualifierName(name: string): Result<QualifierName>;
+/**
+ * Converts a string to a {@link QualifierContextValue} if it is a valid qualifier context value.
+ * @param value - the string to convert
+ * @returns `Success` with the converted {@link QualifierContextValue} if successful, or `Failure` with an
+ * error message if not.
+ * @public
+ */
+export declare function toQualifierContextValue(value: string): Result<QualifierContextValue>;
 /**
  * Converts a number to a {@link QualifierIndex} if it is a valid qualifier index.
  * @param index - the number to convert

package/lib/packlets/common/validate/conditions.js

@@ -37,7 +37,9 @@ exports.isValidConditionSetToken = isValidConditionSetToken;
 exports.isValidConditionSetHash = isValidConditionSetHash;
 exports.isValidDecisionKey = isValidDecisionKey;
 exports.isValidDecisionIndex = isValidDecisionIndex;
+exports.isValidQualifierContextValue = isValidQualifierContextValue;
 exports.toQualifierName = toQualifierName;
+exports.toQualifierContextValue = toQualifierContextValue;
 exports.toQualifierIndex = toQualifierIndex;
 exports.toQualifierTypeName = toQualifierTypeName;
 exports.toQualifierTypeIndex = toQualifierTypeIndex;
@@ -182,6 +184,7 @@ function isValidConditionSetKey(key) {
     if (key === '') {
         return true;
     }
+    /* c8 ignore next 2 - edge case: condition set key validation rarely fails */
     // a condition set key is a `+` separated list of condition keys
     return key.split('+').every(isValidConditionKey);
 }
@@ -224,6 +227,16 @@ function isValidDecisionKey(key) {
 function isValidDecisionIndex(index) {
     return index >= 0;
 }
+/**
+ * Determines whether a string is a valid qualifier context value.
+ * For now, any non-empty string is considered a valid context value.
+ * @param value - the string to validate
+ * @returns true if the string is a valid qualifier context value, false otherwise.
+ * @public
+ */
+function isValidQualifierContextValue(value) {
+    return typeof value === 'string' && value.length > 0;
+}
 /**
  * Converts a string to a {@link QualifierName} if it is a valid qualifier name.
  * @param name - the string to convert
@@ -234,10 +247,23 @@ function isValidDecisionIndex(index) {
 function toQualifierName(name) {
     /* c8 ignore next 3 - functional code path tested but coverage intermittently missed */
     if (!isValidQualifierName(name)) {
-        return (0, ts_utils_1.fail)(`${name}: not a valid qualifier name`);
+        return (0, ts_utils_1.fail)(`${name}: invalid qualifier name`);
     }
     return (0, ts_utils_1.succeed)(name);
 }
+/**
+ * Converts a string to a {@link QualifierContextValue} if it is a valid qualifier context value.
+ * @param value - the string to convert
+ * @returns `Success` with the converted {@link QualifierContextValue} if successful, or `Failure` with an
+ * error message if not.
+ * @public
+ */
+function toQualifierContextValue(value) {
+    if (!isValidQualifierContextValue(value)) {
+        return (0, ts_utils_1.fail)(`${value}: invalid qualifier context value`);
+    }
+    return (0, ts_utils_1.succeed)(value);
+}
 /**
  * Converts a number to a {@link QualifierIndex} if it is a valid qualifier index.
  * @param index - the number to convert
@@ -248,7 +274,7 @@ function toQualifierName(name) {
 function toQualifierIndex(index) {
     /* c8 ignore next 3 - coverage is having a bad day */
     if (!isValidQualifierIndex(index)) {
-        return (0, ts_utils_1.fail)(`${index}: not a valid qualifier index`);
+        return (0, ts_utils_1.fail)(`${index}: invalid qualifier index`);
     }
     return (0, ts_utils_1.succeed)(index);
 }
@@ -262,7 +288,7 @@ function toQualifierIndex(index) {
 function toQualifierTypeName(name) {
     /* c8 ignore next 3 - functional code path tested but coverage intermittently missed */
     if (!isValidQualifierTypeName(name)) {
-        return (0, ts_utils_1.fail)(`${name}: not a valid qualifier type name`);
+        return (0, ts_utils_1.fail)(`${name}: invalid qualifier type name`);
     }
     return (0, ts_utils_1.succeed)(name);
 }
@@ -276,7 +302,7 @@ function toQualifierTypeName(name) {
 function toQualifierTypeIndex(index) {
     /* c8 ignore next 3 - functional code path tested but coverage intermittently missed */
     if (!isValidQualifierTypeIndex(index)) {
-        return (0, ts_utils_1.fail)(`${index}: not a valid qualifier type index`);
+        return (0, ts_utils_1.fail)(`${index}: invalid qualifier type index`);
     }
     return (0, ts_utils_1.succeed)(index);
 }
@@ -541,7 +567,7 @@ function isValidQualifierDefaultValuesToken(token) {
 function toQualifierDefaultValueToken(token) {
     /* c8 ignore next 3 - functional code path tested but coverage intermittently missed */
     if (!isValidQualifierDefaultValueToken(token)) {
-        return (0, ts_utils_1.fail)(`${token}: not a valid qualifier default value token`);
+        return (0, ts_utils_1.fail)(`${token}: invalid qualifier default value token`);
     }
     return (0, ts_utils_1.succeed)(token);
 }
@@ -555,7 +581,7 @@ function toQualifierDefaultValueToken(token) {
 function toQualifierDefaultValuesToken(token) {
     /* c8 ignore next 3 - functional code path tested but coverage intermittently missed */
     if (!isValidQualifierDefaultValuesToken(token)) {
-        return (0, ts_utils_1.fail)(`${token}: not a valid qualifier default values token`);
+        return (0, ts_utils_1.fail)(`${token}: invalid qualifier default values token`);
     }
     return (0, ts_utils_1.succeed)(token);
 }

package/lib/packlets/common/validate/regularExpressions.d.ts

@@ -38,6 +38,10 @@ export declare const conditionSetHash: RegExp;
  * @internal
  */
 export declare const decisionKey: RegExp;
+/**
+ * @internal
+ */
+export declare const candidateValueKey: RegExp;
 /**
  * A {@link QualifierDefaultValueToken | qualifier default value token} has the form
  * `<qualifierName>=<value>` or `<qualifierName>=` (to remove default).

package/lib/packlets/common/validate/regularExpressions.js

@@ -21,7 +21,7 @@
  * SOFTWARE.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.territoryCode = exports.qualifierDefaultValuesToken = exports.qualifierDefaultValueToken = exports.decisionKey = exports.conditionSetHash = exports.contextToken = exports.conditionToken = exports.conditionKey = exports.identifierList = exports.segmentedIdentifier = exports.identifier = void 0;
+exports.territoryCode = exports.qualifierDefaultValuesToken = exports.qualifierDefaultValueToken = exports.candidateValueKey = exports.decisionKey = exports.conditionSetHash = exports.contextToken = exports.conditionToken = exports.conditionKey = exports.identifierList = exports.segmentedIdentifier = exports.identifier = void 0;
 /**
  * @internal
  */
@@ -62,6 +62,10 @@ exports.conditionSetHash = /^[a-zA-Z0-9]{8}$/;
  * @internal
  */
 exports.decisionKey = /^[a-zA-Z0-9]{8}(?:\+[a-zA-Z0-9]{8})*(?:\|[a-zA-Z0-9]{8})?$/;
+/**
+ * @internal
+ */
+exports.candidateValueKey = /^[a-zA-Z0-9]+$/;
 /**
  * A {@link QualifierDefaultValueToken | qualifier default value token} has the form
  * `<qualifierName>=<value>` or `<qualifierName>=` (to remove default).

package/lib/packlets/common/validate/resources.d.ts

@@ -1,5 +1,5 @@
 import { Result } from '@fgv/ts-utils';
-import { ResourceId, ResourceIndex, ResourceName, ResourceTypeIndex, ResourceTypeName } from '../resources';
+import { CandidateValueIndex, CandidateValueKey, ResourceId, ResourceIndex, ResourceName, ResourceTypeIndex, ResourceTypeName } from '../resources';
 /**
  * Checks if the given name is a valid resource name.
  *
@@ -40,6 +40,22 @@ export declare function isValidResourceTypeName(name: string): name is ResourceT
  * @public
  */
 export declare function isValidResourceTypeIndex(index: number): index is ResourceTypeIndex;
+/**
+ * Checks if the given index is a valid candidate value index.
+ *
+ * @param index - The index to validate.
+ * @returns `true` if the index is a valid candidate value index, otherwise `false`.
+ * @public
+ */
+export declare function isValidCandidateValueIndex(index: number): index is CandidateValueIndex;
+/**
+ * Checks if the given key is a valid candidate value key.
+ *
+ * @param key - The key to validate.
+ * @returns `true` if the key is a valid candidate value key, otherwise `false`.
+ * @public
+ */
+export declare function isValidCandidateValueKey(key: string): key is CandidateValueKey;
 /**
  * Converts a string to a {@link ResourceName | resource name}.
  *
@@ -94,4 +110,22 @@ export declare function toResourceTypeName(name: string): Result<ResourceTypeNam
  * @public
  */
 export declare function toResourceTypeIndex(index: number): Result<ResourceTypeIndex>;
+/**
+ * Converts a string to a {@link CandidateValueKey | candidate value key}.
+ *
+ * @param key - The key to convert.
+ * @returns `Success` with the converted key if valid, or `Failure` with an error message
+ * if not.
+ * @public
+ */
+export declare function toCandidateValueKey(key: string): Result<CandidateValueKey>;
+/**
+ * Converts a number to a {@link CandidateValueIndex | candidate value index}.
+ *
+ * @param index - The number to convert.
+ * @returns `Success` with the converted index if valid, or `Failure` with an error message
+ * if not.
+ * @public
+ */
+export declare function toCandidateValueIndex(index: number): Result<CandidateValueIndex>;
 //# sourceMappingURL=resources.d.ts.map