@fgv/ts-res 5.0.0-22 → 5.0.0-23

package/dist/ts-res.d.ts

@@ -1,6 +1,7 @@
 import { Brand } from '@fgv/ts-utils';
 import { Collections } from '@fgv/ts-utils';
 import { Converter } from '@fgv/ts-utils';
+import { Converters } from '@fgv/ts-json-base';
 import { DetailedResult } from '@fgv/ts-utils';
 import { FileTree } from '@fgv/ts-utils';
 import { Hash } from '@fgv/ts-utils';
@@ -132,6 +133,13 @@ declare const allPredefinedSystemConfigurations: ReadonlyArray<PredefinedSystemC
  */
 export declare const allResourceValueMergeMethods: ResourceValueMergeMethod[];
 
+/**
+ * A `Converter` for {@link QualifierTypes.Config.IAnyQualifierTypeConfig | AnyQualifierTypeConfig} objects.
+ * @returns A `Converter` for {@link QualifierTypes.Config.IAnyQualifierTypeConfig | AnyQualifierTypeConfig} objects.
+ * @public
+ */
+declare const anyQualifierTypeConfig: Converter<Model_2.IAnyQualifierTypeConfig, unknown>;
+
 /**
  * Converts an array of {@link Helpers.IConditionTokenParts | condition token parts} into an array of
  * syntactically validated {@link ConditionToken | condition tokens}.
@@ -577,6 +585,120 @@ declare class CandidateReducer {
     reduceCandidate(candidate: ResourceCandidate): Result<IReducedCandidate | undefined>;
 }
 
+/**
+ * Implementation of a candidate value that stores normalized JSON data.
+ * The value is normalized on creation and a hash-based key is generated
+ * for efficient deduplication.
+ * @public
+ */
+declare class CandidateValue implements ICandidateValue {
+    private readonly _collectible;
+    private readonly _json;
+    /**
+     * The unique key for this candidate value.
+     */
+    get key(): CandidateValueKey;
+    /**
+     * The index of this candidate value in the collection.
+     */
+    get index(): CandidateValueIndex | undefined;
+    /**
+     * The normalized JSON value.
+     */
+    get json(): JsonValue;
+    /**
+     * Constructor for a {@link Resources.CandidateValue} object.
+     * @param params - Parameters to create the candidate value.
+     * @internal
+     */
+    protected constructor(params: ICandidateValueCreateParams);
+    /**
+     * Creates a new {@link Resources.CandidateValue} object.
+     * @param params - Parameters to create the candidate value.
+     * @returns `Success` with the new candidate value if successful,
+     * or `Failure` with an error message if not.
+     * @public
+     */
+    static create(params: ICandidateValueCreateParams): Result<CandidateValue>;
+    /**
+     * Sets the index of this candidate value.
+     * @param index - The index to set.
+     * @returns `Success` with the index if successful, or `Failure` with an error message if not.
+     * @public
+     */
+    setIndex(index: number): Result<CandidateValueIndex>;
+}
+
+/**
+ * A `ValidatingCollector` for {@link Resources.CandidateValue | CandidateValues},
+ * which collects candidate values supplied as either {@link Resources.CandidateValue | CandidateValue} or
+ * `JsonValue`.
+ * @public
+ */
+declare class CandidateValueCollector extends ValidatingCollector<CandidateValue> {
+    readonly normalizer: Hash.HashingNormalizer;
+    /**
+     * Constructor for a {@link Resources.CandidateValueCollector} object.
+     * @param params - Parameters to create the collector.
+     * @internal
+     */
+    protected constructor(params?: ICandidateValueCollectorCreateParams);
+    /**
+     * Creates a new {@link Resources.CandidateValueCollector} object.
+     * @param params - Parameters to create the collector.
+     * @returns `Success` with the new collector if successful,
+     * or `Failure` with an error message if not.
+     * @public
+     */
+    static create(params?: ICandidateValueCollectorCreateParams): Result<CandidateValueCollector>;
+    /**
+     * Returns an array of JSON values ordered by their indices.
+     * @returns Array of JsonValue objects in index order.
+     * @public
+     */
+    getValuesByIndex(): JsonValue[];
+    /**
+     * Converter method to handle CandidateValue | JsonValue.
+     * @param from - The value to convert.
+     * @returns `Success` with the CandidateValue if successful, or `Failure` with an error message if not.
+     * @internal
+     */
+    private _toCandidateValue;
+}
+
+/**
+ * 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 declare type CandidateValueIndex = Brand<number, 'CandidateValueIndex'>;
+
+/**
+ * `Converter` which validates an `unknown` value as a {@link CandidateValueIndex | CandidateValueIndex}.
+ * @public
+ */
+declare const candidateValueIndex: Converter<CandidateValueIndex, unknown>;
+
+/**
+ * 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 declare type CandidateValueKey = Brand<string, 'CandidateValueKey'>;
+
+/**
+ * `Converter` which validates an `unknown` value as a {@link CandidateValueKey | CandidateValueKey}.
+ * @public
+ */
+declare const candidateValueKey: Converter<CandidateValueKey, unknown>;
+
+/**
+ * @internal
+ */
+declare const candidateValueKey_2: RegExp;
+
 /**
  * A factory that chains multiple factories together.
  * @public
@@ -708,6 +830,8 @@ declare namespace Common {
         ResourceValueMergeMethod,
         allResourceValueMergeMethods,
         CandidateCompleteness,
+        CandidateValueIndex,
+        CandidateValueKey,
         IResourceResolver
     }
 }
@@ -804,23 +928,28 @@ declare class CompiledResourceCollection implements IResourceManager<IResource>
     private readonly _qualifierTypes;
     private readonly _qualifiers;
     private readonly _resourceTypes;
+    private readonly _candidateValues;
     private readonly _builtResources;
     private _cachedResourceTree?;
     /**
-     * A {@link QualifierTypes.QualifierTypeCollector | QualifierTypeCollector} which
+     * A {@link QualifierTypes.ReadOnlyQualifierTypeCollector | ReadOnlyQualifierTypeCollector} which
      * contains the {@link QualifierTypes.QualifierType | qualifier types} used in this collection.
      */
-    get qualifierTypes(): QualifierTypeCollector;
+    get qualifierTypes(): ReadOnlyQualifierTypeCollector;
     /**
-     * A {@link Qualifiers.QualifierCollector | QualifierCollector} which
+     * A {@link Qualifiers.IReadOnlyQualifierCollector | ReadOnlyQualifierCollector} which
      * contains the {@link Qualifiers.Qualifier | qualifiers} used in this collection.
      */
-    get qualifiers(): QualifierCollector;
+    get qualifiers(): IReadOnlyQualifierCollector;
     /**
      * A {@link ResourceTypes.ResourceTypeCollector | ResourceTypeCollector} which
      * contains the {@link ResourceTypes.ResourceType | resource types} used in this collection.
      */
-    get resourceTypes(): ResourceTypeCollector;
+    get resourceTypes(): ReadOnlyResourceTypeCollector;
+    /**
+     * The candidate values in the collection.
+     */
+    get candidateValues(): ReadonlyArray<JsonValue>;
     /**
      * {@inheritdoc Runtime.IResourceManager.builtResources}
      */
@@ -918,6 +1047,12 @@ declare class CompiledResourceCollection implements IResourceManager<IResource>
      * @internal
      */
     private _buildDecisions;
+    /**
+     * Gets a candidate value from the collection.
+     * @param valueIndex - The index of the candidate value to get.
+     * @returns
+     */
+    private _getCandidateValue;
     /**
      * Reconstructs a ValidatingResultMap of resources from compiled data.
      * @param compiled - The compiled resource collection
@@ -1714,6 +1849,7 @@ declare namespace Config_2 {
         isSystemQualifierTypeConfig,
         IQualifierTypeConfig,
         ILanguageQualifierTypeConfig,
+        LiteralValueHierarchyDecl,
         ITerritoryQualifierTypeConfig,
         ILiteralQualifierTypeConfig,
         ISystemLanguageQualifierTypeConfig,
@@ -2071,6 +2207,8 @@ declare namespace Convert {
         resourceIndex,
         resourceTypeName,
         resourceTypeIndex,
+        candidateValueKey,
+        candidateValueIndex,
         resourceValueMergeMethod,
         contextQualifierToken,
         contextToken,
@@ -2117,13 +2255,16 @@ declare namespace Convert_12 {
 
 declare namespace Convert_2 {
     export {
+        qualifierTypeConfig,
         languageQualifierTypeConfig,
         territoryQualifierTypeConfig,
         literalQualifierTypeConfig,
         systemLanguageQualifierTypeConfig,
         systemTerritoryQualifierTypeConfig,
         systemLiteralQualifierTypeConfig,
-        systemQualifierTypeConfig
+        systemQualifierTypeConfig,
+        jsonQualifierTypeConfig,
+        anyQualifierTypeConfig
     }
 }
 
@@ -2214,7 +2355,7 @@ declare namespace Convert_9 {
  * if successful, `Failure` with an error message otherwise.
  * @public
  */
-declare function createQualifierTypeFromConfig(typeConfig: Config_2.IQualifierTypeConfig<JsonObject>): Result<QualifierType>;
+declare function createQualifierTypeFromConfig(typeConfig: Config_2.IAnyQualifierTypeConfig): Result<QualifierType>;
 
 /**
  * Creates a {@link QualifierTypes.QualifierType | QualifierType} from a system configuration object.
@@ -2870,6 +3011,69 @@ declare interface ICandidateInfo {
     readonly json?: JsonObject;
 }
 
+/**
+ * Interface for a candidate value that can be collected and indexed.
+ * Candidate values are normalized JSON values that can be shared across
+ * multiple resource candidates to reduce duplication.
+ * @public
+ */
+declare interface ICandidateValue extends Collections.ICollectible<CandidateValueKey, CandidateValueIndex> {
+    /**
+     * The unique key for this candidate value, derived from the hash of the normalized JSON.
+     */
+    readonly key: CandidateValueKey;
+    /**
+     * The index of this candidate value in the collection.
+     */
+    readonly index: CandidateValueIndex | undefined;
+    /**
+     * The normalized JSON value.
+     */
+    readonly json: JsonValue;
+    /**
+     * Sets the index of this candidate value.
+     * @param index - The index to set.
+     * @returns `Success` with the index if successful, or `Failure` with an error message if not.
+     */
+    setIndex(index: number): Result<CandidateValueIndex>;
+}
+
+/**
+ * Parameters for creating a {@link Resources.CandidateValueCollector}.
+ * @public
+ */
+declare interface ICandidateValueCollectorCreateParams {
+    /**
+     * Optional normalizer to use for normalizing JSON values.
+     * If not provided, a default Crc32Normalizer will be used.
+     */
+    normalizer?: Hash.HashingNormalizer;
+    /**
+     * Optional initial candidate values to add to the collection.
+     */
+    candidateValues?: (CandidateValue | JsonValue)[];
+}
+
+/**
+ * Parameters for creating a {@link Resources.CandidateValue | CandidateValue}.
+ * @public
+ */
+declare interface ICandidateValueCreateParams {
+    /**
+     * The JSON value to store. Will be normalized during creation.
+     */
+    json: JsonValue;
+    /**
+     * Optional normalizer to use for normalizing the JSON value.
+     * If not provided, a default Crc32Normalizer will be used.
+     */
+    normalizer?: Hash.Crc32Normalizer;
+    /**
+     * Optional index if the value is already indexed.
+     */
+    index?: number;
+}
+
 /**
  * Non-validated child declaration of a {@link Conditions.Condition | condition}.
  * @public
@@ -2993,9 +3197,9 @@ declare interface ICompiledAbstractDecision {
  */
 declare interface ICompiledCandidate {
     /**
-     * The JSON value of the candidate.
+     * The global index of the JSON value of the candidate.
      */
-    json: JsonValue;
+    valueIndex: Common.CandidateValueIndex;
     /**
      * Indicates if this is a partial resource that needs to be merged.
      */
@@ -3168,6 +3372,10 @@ declare interface ICompiledResourceCollection {
      * Array of all decisions in the collection.
      */
     decisions: ReadonlyArray<ICompiledAbstractDecision>;
+    /**
+     * Array of all candidate values in the collection.
+     */
+    candidateValues: ReadonlyArray<JsonValue>;
     /**
      * Array of all resources in the collection.
      */
@@ -3898,10 +4106,10 @@ declare interface ILiteralQualifierTypeCreateParams {
      */
     enumeratedValues?: ReadonlyArray<string>;
     /**
-     * Optional {@link QualifierTypes.LiteralValueHierarchyDecl | hierarchy declaration}
+     * Optional {@link QualifierTypes.Config.LiteralValueHierarchyDecl | hierarchy declaration}
      * of literal values to use for matching. If not provided, no hierarchy will be used.
      */
-    hierarchy?: LiteralValueHierarchyDecl<string>;
+    hierarchy?: Config_2.LiteralValueHierarchyDecl<string>;
     /**
      * Global index for this qualifier type.
      */
@@ -4360,6 +4568,10 @@ declare interface IQualifierType extends ICollectible<QualifierTypeName, Qualifi
      * The name of the qualifier type.
      */
     readonly name: QualifierTypeName;
+    /**
+     * Name of the underlying system type.
+     */
+    readonly systemTypeName: QualifierTypeName;
     /**
      * Unique key for this qualifier.
      */
@@ -4422,6 +4634,17 @@ declare interface IQualifierType extends ICollectible<QualifierTypeName, Qualifi
      * Sets the index for this qualifier type. Once set, index is immutable.
      */
     setIndex(index: number): Result<QualifierTypeIndex>;
+    /**
+     * Gets the configuration for this qualifier type.
+     * @returns `Success` with the configuration if successful, `Failure` with an error message otherwise.
+     */
+    getConfigurationJson(): Result<JsonObject>;
+    /**
+     * Validates configuration JSON data for this qualifier type.
+     * @param from - The unknown data to validate as configuration JSON.
+     * @returns `Success` with validated JSON configuration if valid, `Failure` with an error message otherwise.
+     */
+    validateConfigurationJson(from: unknown): Result<JsonObject>;
 }
 
 /**
@@ -4582,7 +4805,7 @@ declare interface IReadOnlyResourceTreeBranch<T> {
  * Interface for a read-only result-based resource tree with navigation methods.
  * @public
  */
-declare interface IReadOnlyResourceTreeChildren<T, TID extends string = ResourceId, TNAME extends string = ResourceName> extends IReadOnlyResultMap<ResourceName, IReadOnlyResourceTreeNode<T>> {
+declare interface IReadOnlyResourceTreeChildren<T, TID extends string = ResourceId, TNAME extends string = ResourceName> extends IReadOnlyResultMap<TNAME, IReadOnlyResourceTreeNode<T>> {
     /**
      * Gets a tree node by its full ResourceId path.
      * @param id - The ResourceId path to look up
@@ -4698,6 +4921,7 @@ declare interface IResourceBuilderCreateParams {
     conditionSets: ConditionSetCollector;
     resourceTypes: ReadOnlyResourceTypeCollector;
     decisions: AbstractDecisionCollector;
+    candidateValues: CandidateValueCollector;
 }
 
 /**
@@ -4727,6 +4951,7 @@ declare interface IResourceCandidateCreateParams {
     resourceType?: ResourceType;
     parentConditions?: ReadonlyArray<Condition>;
     conditionSets: ConditionSetCollector;
+    candidateValues: CandidateValueCollector;
 }
 
 /**
@@ -5273,6 +5498,24 @@ declare function isResourceTreeRootOrNodeInit<T>(init: ResourceTreeNodeInit<T> |
  */
 declare function isSystemQualifierTypeConfig(config: IAnyQualifierTypeConfig): config is ISystemQualifierTypeConfig;
 
+/**
+ * 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
+ */
+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
+ */
+declare function isValidCandidateValueKey(key: string): key is CandidateValueKey;
+
 /**
  * Determines whether a number is a valid condition index.
  * @param index - the number to validate
@@ -5501,7 +5744,7 @@ declare interface ISystemConfiguration {
     /** Optional description explaining the purpose and use case of the configuration. */
     description?: string;
     /** Qualifier type configurations that define the available qualifier types in the system. */
-    qualifierTypes: QualifierTypes.Config.ISystemQualifierTypeConfig[];
+    qualifierTypes: QualifierTypes.Config.IAnyQualifierTypeConfig[];
     /** Qualifier declarations that define the available qualifiers in the system. */
     qualifiers: Qualifiers.IQualifierDecl[];
     /** Resource type configurations that define the available resource types in the system. */
@@ -5570,7 +5813,7 @@ declare interface ITerritoryQualifierTypeConfig {
     acceptLowercase?: boolean;
     allowedTerritories?: string[];
     /**
-     * Optional {@link QualifierTypes.LiteralValueHierarchyDecl | hierarchy declaration}
+     * Optional {@link QualifierTypes.Config.LiteralValueHierarchyDecl | hierarchy declaration}
      * of territory values to use for matching. If not provided, no hierarchy will be used.
      */
     hierarchy?: LiteralValueHierarchyDecl<string>;
@@ -5603,10 +5846,10 @@ declare interface ITerritoryQualifierTypeCreateParams {
      */
     acceptLowercase?: boolean;
     /**
-     * Optional {@link QualifierTypes.LiteralValueHierarchyDecl | hierarchy declaration}
+     * Optional {@link QualifierTypes.Config.LiteralValueHierarchyDecl | hierarchy declaration}
      * of territory values to use for matching. If not provided, no hierarchy will be used.
      */
-    hierarchy?: LiteralValueHierarchyDecl<string>;
+    hierarchy?: Config_2.LiteralValueHierarchyDecl<string>;
 }
 
 /**
@@ -5923,11 +6166,22 @@ declare class JsonImporter implements IImporter {
     private _tryImportResourceTree;
 }
 
+/**
+ * A `Converter` for {@link QualifierTypes.Config.IQualifierTypeConfig | QualifierTypeConfig} objects.
+ * @returns A `Converter` for {@link QualifierTypes.Config.IQualifierTypeConfig | QualifierTypeConfig} objects.
+ * @public
+ */
+declare const jsonQualifierTypeConfig: Converter<Model_2.IQualifierTypeConfig<JsonObject>, Converters.IJsonConverterContext>;
+
 /**
  * Implementation of a {@link ResourceTypes.ResourceType | ResourceType} for JSON values.
  * @public
  */
 declare class JsonResourceType extends ResourceType<JsonObject> {
+    /**
+     * {@inheritdoc ResourceTypes.ResourceType.systemTypeName}
+     */
+    readonly systemTypeName: ResourceTypeName;
     /**
      * Protected {@link ResourceTypes.JsonResourceType | JsonResourceType} constructor for use by subclasses.
      * Use {@link ResourceTypes.JsonResourceType.create | JsonResourceType.create} to create a new instance.
@@ -5985,6 +6239,10 @@ declare const LanguagePrioritySystemConfiguration: ISystemConfiguration;
  * @public
  */
 declare class LanguageQualifierType extends QualifierType {
+    /**
+     * {@inheritdoc QualifierTypes.IQualifierType.systemTypeName}
+     */
+    readonly systemTypeName: QualifierTypeName;
     /**
      * Creates a new instance of a {@link QualifierTypes.LanguageQualifierType | language qualifier type}.
      * @param name - Optional name for the qualifier type. Defaults to 'language'.
@@ -6014,6 +6272,27 @@ declare class LanguageQualifierType extends QualifierType {
      * {@inheritdoc QualifierTypes.IQualifierType.isValidConditionValue}
      */
     isValidConditionValue(value: string): value is QualifierConditionValue;
+    /**
+     * Gets a {@link QualifierTypes.Config.ISystemLanguageQualifierTypeConfig | strongly typed configuration object}
+     * for this qualifier type.
+     * @returns `Success` with the configuration if successful, `Failure` with an error message otherwise.
+     */
+    getConfiguration(): Result<Config_2.ISystemLanguageQualifierTypeConfig>;
+    /**
+     * {@inheritdoc QualifierTypes.IQualifierType.getConfigurationJson}
+     */
+    getConfigurationJson(): Result<JsonObject>;
+    /**
+     * {@inheritdoc QualifierTypes.IQualifierType.validateConfigurationJson}
+     */
+    validateConfigurationJson(from: unknown): Result<JsonObject>;
+    /**
+     * Validates a {@link QualifierTypes.Config.ISystemLanguageQualifierTypeConfig | strongly typed configuration object}
+     * for this qualifier type.
+     * @param from - The unknown data to validate as a configuration object.
+     * @returns `Success` with the validated configuration if successful, `Failure` with an error message otherwise.
+     */
+    validateConfiguration(from: unknown): Result<Config_2.ISystemLanguageQualifierTypeConfig>;
     /**
      * Matches a single language condition against a single language context value using
      * {@link https://github.com/ErikFortune/fgv/tree/main/libraries/ts-bcp47#tag-matching | similarity matching}.
@@ -6038,6 +6317,10 @@ declare const languageQualifierTypeConfig: ObjectConverter<Model_2.ILanguageQual
  * @public
  */
 declare class LiteralQualifierType extends QualifierType {
+    /**
+     * {@inheritdoc QualifierTypes.IQualifierType.systemTypeName}
+     */
+    readonly systemTypeName: QualifierTypeName;
     /**
      * Indicates whether the qualifier match is case-sensitive.
      */
@@ -6073,6 +6356,27 @@ declare class LiteralQualifierType extends QualifierType {
      * {@inheritdoc QualifierTypes.IQualifierType.isPotentialMatch}
      */
     isPotentialMatch(conditionValue: string, contextValue: string): boolean;
+    /**
+     * Gets a {@link QualifierTypes.Config.ISystemLiteralQualifierTypeConfig | strongly typed configuration object}
+     * for this qualifier type.
+     * @returns `Success` with the configuration if successful, `Failure` with an error message otherwise.
+     */
+    getConfiguration(): Result<Config_2.ISystemLiteralQualifierTypeConfig>;
+    /**
+     * {@inheritdoc QualifierTypes.IQualifierType.getConfigurationJson}
+     */
+    getConfigurationJson(): Result<JsonObject>;
+    /**
+     * {@inheritdoc QualifierTypes.IQualifierType.validateConfigurationJson}
+     */
+    validateConfigurationJson(from: unknown): Result<JsonObject>;
+    /**
+     * Validates a {@link QualifierTypes.Config.ISystemLiteralQualifierTypeConfig | strongly typed configuration object}
+     * for this qualifier type.
+     * @param from - The unknown data to validate as a configuration object.
+     * @returns `Success` with the validated configuration if successful, `Failure` with an error message otherwise.
+     */
+    validateConfiguration(from: unknown): Result<Config_2.ISystemLiteralQualifierTypeConfig>;
     /**
      * {@inheritdoc QualifierTypes.QualifierType._matchOne}
      */
@@ -6202,6 +6506,11 @@ declare class LiteralValueHierarchy<T extends string = string> {
      */
     match(condition: QualifierConditionValue, context: QualifierContextValue, __operator?: ConditionOperator): QualifierMatchScore;
     protected static _buildValuesFromHierarchy<T extends string>(params: ILiteralValueHierarchyCreateParams<T>): Result<ReadonlyMap<T, ILiteralValue<T>>>;
+    /**
+     * Converts the hierarchy to a record of parent-child relationships.
+     * @returns A record of parent-child relationships.
+     */
+    asRecord(): Record<string, string>;
 }
 
 /**
@@ -6387,6 +6696,7 @@ declare namespace Model_2 {
         isSystemQualifierTypeConfig,
         IQualifierTypeConfig,
         ILanguageQualifierTypeConfig,
+        LiteralValueHierarchyDecl,
         ITerritoryQualifierTypeConfig,
         ILiteralQualifierTypeConfig,
         ISystemLanguageQualifierTypeConfig,
@@ -6986,6 +7296,10 @@ export declare abstract class QualifierType implements IQualifierType {
      * {@inheritdoc QualifierTypes.IQualifierType.name}
      */
     readonly name: QualifierTypeName;
+    /**
+     * {@inheritdoc QualifierTypes.IQualifierType.systemTypeName}
+     */
+    abstract readonly systemTypeName: QualifierTypeName;
     /**
      * {@inheritdoc QualifierTypes.IQualifierType.key}
      */
@@ -7031,6 +7345,14 @@ export declare abstract class QualifierType implements IQualifierType {
      * {@inheritdoc QualifierTypes.IQualifierType.matches}
      */
     matches(condition: QualifierConditionValue, context: QualifierContextValue, operator: ConditionOperator): QualifierMatchScore;
+    /**
+     * {@inheritdoc QualifierTypes.IQualifierType.getConfigurationJson}
+     */
+    abstract getConfigurationJson(): Result<JsonObject>;
+    /**
+     * {@inheritdoc QualifierTypes.IQualifierType.validateConfigurationJson}
+     */
+    abstract validateConfigurationJson(from: unknown): Result<JsonObject>;
     /**
      * {@inheritdoc QualifierTypes.IQualifierType.setIndex}
      */
@@ -7110,6 +7432,14 @@ declare class QualifierTypeCollector extends ValidatingConvertingCollector<Quali
     protected static _toQualifierType(from: unknown): Result<QualifierType>;
 }
 
+/**
+ * A `Converter` for {@link QualifierTypes.Config.IQualifierTypeConfig | QualifierTypeConfig} objects.
+ * @returns A `Converter` for {@link QualifierTypes.Config.IQualifierTypeConfig | QualifierTypeConfig} objects.
+ * @param config - A `Converter` for the configuration object.
+ * @public
+ */
+declare function qualifierTypeConfig<T, TD = unknown>(config: Converter<T, TD>): Converter<Model_2.IQualifierTypeConfig<T>, TD>;
+
 /**
  * A factory that creates a {@link QualifierTypes.QualifierType | QualifierType} from a {@link QualifierTypes.Config.IAnyQualifierTypeConfig | system qualifier type configuration}
  * by chaining a supplied factory with a {@link Config.BuiltInQualifierTypeFactory | built-in factory} that handles built-in qualifier types.
@@ -7159,7 +7489,6 @@ declare namespace QualifierTypes {
         LanguageQualifierType,
         ILiteralQualifierTypeCreateParams,
         LiteralQualifierType,
-        LiteralValueHierarchyDecl,
         ILiteralValue,
         ILiteralValueHierarchyCreateParams,
         LiteralValueHierarchy,
@@ -7337,6 +7666,7 @@ declare namespace RegularExpressions {
         contextToken_2 as contextToken,
         conditionSetHash_2 as conditionSetHash,
         decisionKey_2 as decisionKey,
+        candidateValueKey_2 as candidateValueKey,
         qualifierDefaultValueToken_2 as qualifierDefaultValueToken,
         qualifierDefaultValuesToken_2 as qualifierDefaultValuesToken,
         territoryCode
@@ -7493,6 +7823,10 @@ declare class ResourceBuilder {
      * Collector for {@link Decisions.AbstractDecision | abstract decisions}.
      */
     protected _decisions: AbstractDecisionCollector;
+    /**
+     * Collector for candidate values.
+     */
+    protected _candidateValues: CandidateValueCollector;
     /**
      * Constructor for a {@link Resources.ResourceBuilder | ResourceBuilder} object.
      * @param params - Parameters to construct the new {@link Resources.ResourceBuilder | ResourceBuilder}.
@@ -7570,10 +7904,16 @@ export declare class ResourceCandidate implements IResourceCandidate {
      * is a possible instance.
      */
     readonly id: ResourceId;
+    /**
+     * The candidate value that contains the JSON representation of the instance data.
+     */
+    readonly candidateValue: CandidateValue;
     /**
      * The JSON representation of the instance data to be applied.
+     * @remarks
+     * This property provides access to the JSON data from the underlying candidate value.
      */
-    readonly json: JsonObject;
+    get json(): JsonObject;
     /**
      * The conditions under which this candidate applies.
      */
@@ -7837,6 +8177,11 @@ export declare class ResourceManagerBuilder implements IResourceManager<Resource
      * @internal
      */
     protected readonly _decisions: AbstractDecisionCollector;
+    /**
+     * The candidate value collector used by this resource manager.
+     * @internal
+     */
+    protected readonly _candidateValues: CandidateValueCollector;
     /**
      * The {@link Resources.ResourceBuilder | resource builders} used by this resource manager.
      * @internal
@@ -8163,6 +8508,7 @@ export declare class ResourceManagerBuilder implements IResourceManager<Resource
      * @param decision - The decision containing condition sets.
      * @param resourceType - The resource type for the candidates.
      * @param builder - The builder to add candidates to.
+     * @param candidateValues - Array of candidate values indexed by valueIndex.
      * @returns `Success` if all candidates were added successfully, `Failure` otherwise.
      * @internal
      */
@@ -8436,6 +8782,11 @@ declare namespace Resources {
         ICandidateInfo,
         IReducedCandidate,
         CandidateReducer,
+        ICandidateValue,
+        ICandidateValueCreateParams,
+        CandidateValue,
+        ICandidateValueCollectorCreateParams,
+        CandidateValueCollector,
         IResourceCandidateCreateParams,
         ICandidateDeclOptions,
         ResourceCandidate,
@@ -8604,6 +8955,10 @@ export declare abstract class ResourceType<T = unknown> implements IResourceType
      * {@inheritdoc ResourceTypes.IResourceType.key}
      */
     get key(): ResourceTypeName;
+    /**
+     * Name of the underlying system type.
+     */
+    abstract readonly systemTypeName: ResourceTypeName;
     /**
      * {@inheritdoc ResourceTypes.IResourceType.index}
      */
@@ -9053,6 +9408,10 @@ declare const TerritoryPrioritySystemConfiguration: ISystemConfiguration;
  * @public
  */
 declare class TerritoryQualifierType extends QualifierType {
+    /**
+     * {@inheritdoc QualifierTypes.IQualifierType.systemTypeName}
+     */
+    readonly systemTypeName: QualifierTypeName;
     /**
      * Optional array enumerating allowed territories to further constrain the type.
      */
@@ -9094,6 +9453,25 @@ declare class TerritoryQualifierType extends QualifierType {
      * @public
      */
     static createFromConfig(config: Config_2.IQualifierTypeConfig<Config_2.ITerritoryQualifierTypeConfig>): Result<TerritoryQualifierType>;
+    /**
+     * {@inheritdoc QualifierTypes.IQualifierType.getConfigurationJson}
+     */
+    getConfiguration(): Result<Config_2.ISystemTerritoryQualifierTypeConfig>;
+    /**
+     * {@inheritdoc QualifierTypes.IQualifierType.getConfigurationJson}
+     */
+    getConfigurationJson(): Result<JsonObject>;
+    /**
+     * {@inheritdoc QualifierTypes.IQualifierType.validateConfigurationJson}
+     */
+    validateConfigurationJson(from: unknown): Result<JsonObject>;
+    /**
+     * Validates a {@link QualifierTypes.Config.ISystemTerritoryQualifierTypeConfig | strongly typed configuration object}
+     * for this qualifier type.
+     * @param from - The unknown data to validate as a configuration object.
+     * @returns `Success` with the validated configuration if successful, `Failure` with an error message otherwise.
+     */
+    validateConfiguration(from: unknown): Result<Config_2.ISystemTerritoryQualifierTypeConfig>;
     /**
      * {@inheritdoc QualifierTypes.QualifierType._matchOne}
      */
@@ -9126,6 +9504,26 @@ declare class TerritoryQualifierType extends QualifierType {
  */
 declare const territoryQualifierTypeConfig: ObjectConverter<Model_2.ITerritoryQualifierTypeConfig, unknown>;
 
+/**
+ * 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
+ */
+declare function toCandidateValueIndex(index: number): Result<CandidateValueIndex>;
+
+/**
+ * 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
+ */
+declare function toCandidateValueKey(key: string): Result<CandidateValueKey>;
+
 /**
  * Converts a number to a {@link ConditionIndex} if it is a valid condition index.
  * @param index - the number to convert
@@ -9425,12 +9823,16 @@ declare namespace Validate {
         isValidResourceIndex,
         isValidResourceTypeName,
         isValidResourceTypeIndex,
+        isValidCandidateValueIndex,
+        isValidCandidateValueKey,
         toResourceName,
         toResourceId,
         toOptionalResourceId,
         toResourceIndex,
         toResourceTypeName,
-        toResourceTypeIndex
+        toResourceTypeIndex,
+        toCandidateValueKey,
+        toCandidateValueIndex
     }
 }
 export { Validate }