@fgv/ts-res 5.0.0-21 → 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
@@ -707,7 +829,10 @@ declare namespace Common {
         ResourceTypeIndex,
         ResourceValueMergeMethod,
         allResourceValueMergeMethods,
-        CandidateCompleteness
+        CandidateCompleteness,
+        CandidateValueIndex,
+        CandidateValueKey,
+        IResourceResolver
     }
 }
 
@@ -803,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}
      */
@@ -917,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
@@ -1713,6 +1849,7 @@ declare namespace Config_2 {
         isSystemQualifierTypeConfig,
         IQualifierTypeConfig,
         ILanguageQualifierTypeConfig,
+        LiteralValueHierarchyDecl,
         ITerritoryQualifierTypeConfig,
         ILiteralQualifierTypeConfig,
         ISystemLanguageQualifierTypeConfig,
@@ -2070,6 +2207,8 @@ declare namespace Convert {
         resourceIndex,
         resourceTypeName,
         resourceTypeIndex,
+        candidateValueKey,
+        candidateValueIndex,
         resourceValueMergeMethod,
         contextQualifierToken,
         contextToken,
@@ -2116,13 +2255,16 @@ declare namespace Convert_12 {
 
 declare namespace Convert_2 {
     export {
+        qualifierTypeConfig,
         languageQualifierTypeConfig,
         territoryQualifierTypeConfig,
         literalQualifierTypeConfig,
         systemLanguageQualifierTypeConfig,
         systemTerritoryQualifierTypeConfig,
         systemLiteralQualifierTypeConfig,
-        systemQualifierTypeConfig
+        systemQualifierTypeConfig,
+        jsonQualifierTypeConfig,
+        anyQualifierTypeConfig
     }
 }
 
@@ -2213,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.
@@ -2869,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
@@ -2992,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.
      */
@@ -3167,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.
      */
@@ -3828,6 +4037,11 @@ declare interface IJsonResourceTypeCreateParams {
      * instance.
      */
     index?: number;
+    /**
+     * Optional template for new instances of {@link ResourceTypes.JsonResourceType | JsonResourceType}
+     * resources.
+     */
+    template?: JsonObject;
 }
 
 /**
@@ -3892,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.
      */
@@ -4354,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.
      */
@@ -4416,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>;
 }
 
 /**
@@ -4576,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
@@ -4692,6 +4921,7 @@ declare interface IResourceBuilderCreateParams {
     conditionSets: ConditionSetCollector;
     resourceTypes: ReadOnlyResourceTypeCollector;
     decisions: AbstractDecisionCollector;
+    candidateValues: CandidateValueCollector;
 }
 
 /**
@@ -4721,6 +4951,7 @@ declare interface IResourceCandidateCreateParams {
     resourceType?: ResourceType;
     parentConditions?: ReadonlyArray<Condition>;
     conditionSets: ConditionSetCollector;
+    candidateValues: CandidateValueCollector;
 }
 
 /**
@@ -4960,6 +5191,31 @@ declare interface IResourceManagerCloneOptions extends IResourceDeclarationOptio
     readonly resourceTypes?: ReadOnlyResourceTypeCollector;
 }
 
+/**
+ * Minimal resource resolver
+ * @public
+ */
+export declare interface IResourceResolver {
+    /**
+     * 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>;
+}
+
 /**
  * A listener for {@link Runtime.ResourceResolver | ResourceResolver} cache activity.
  * @public
@@ -5161,11 +5417,14 @@ declare interface IResourceType<T = unknown> extends ICollectible<ResourceTypeNa
     /**
      * Creates a template for a new resource of this type.
      * The template provides a default structure for creating new resource instances.
-     * @param resourceId - The id for the new resource
-     * @returns A loose resource declaration with default values for this resource type
+     * @param resourceId - The id for the new resource.
+     * @param init - An optional initial value for the resource.
+     * @param resolver - An optional resource resolver that can be used to create the template.
+     * @param conditions - An optional set of conditions that must be met for the resource to be selected.
+     * @returns A loose resource declaration with default values for this resource type.
      * @public
      */
-    createTemplate(resourceId: ResourceId): ResourceJson.Json.ILooseResourceDecl;
+    createTemplate(resourceId: ResourceId, init?: JsonValue, conditions?: ResourceJson.Json.ConditionSetDecl, resolver?: IResourceResolver): Result<ResourceJson.Json.ILooseResourceDecl>;
 }
 
 /**
@@ -5175,6 +5434,7 @@ declare interface IResourceType<T = unknown> extends ICollectible<ResourceTypeNa
 declare interface IResourceTypeConfig {
     name: string;
     typeName: string;
+    template?: JsonObject;
 }
 
 /**
@@ -5238,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
@@ -5466,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. */
@@ -5535,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>;
@@ -5568,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>;
 }
 
 /**
@@ -5888,18 +6166,29 @@ 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.
      * @param key - The key for the new {@link ResourceTypes.JsonResourceType | JsonResourceType} instance.
      * @param index - Optional index for the new {@link ResourceTypes.JsonResourceType | JsonResourceType} instance.
      */
-    protected constructor(key: ResourceTypeName, index?: number);
+    protected constructor(key: ResourceTypeName, index?: number, template?: JsonObject);
     /**
      * Factory method to create a new {@link ResourceTypes.JsonResourceType | JsonResourceType} instance.
      * @param params - {@link ResourceTypes.IJsonResourceTypeCreateParams | Parameters} to create the new instance.
@@ -5923,11 +6212,6 @@ declare class JsonResourceType extends ResourceType<JsonObject> {
      * {@inheritdoc ResourceTypes.ResourceType.(validate:3)}
      */
     validate(json: JsonObject, completeness: 'partial'): Result<JsonObject>;
-    /**
-     * Gets the default template value for a JSON resource type.
-     * @returns An empty object as the default JSON value
-     */
-    protected getDefaultTemplateValue(): JsonObject;
 }
 
 /**
@@ -5955,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'.
@@ -5984,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}.
@@ -6008,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.
      */
@@ -6043,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}
      */
@@ -6172,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>;
 }
 
 /**
@@ -6357,6 +6696,7 @@ declare namespace Model_2 {
         isSystemQualifierTypeConfig,
         IQualifierTypeConfig,
         ILanguageQualifierTypeConfig,
+        LiteralValueHierarchyDecl,
         ITerritoryQualifierTypeConfig,
         ILiteralQualifierTypeConfig,
         ISystemLanguageQualifierTypeConfig,
@@ -6956,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}
      */
@@ -7001,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}
      */
@@ -7080,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.
@@ -7129,7 +7489,6 @@ declare namespace QualifierTypes {
         LanguageQualifierType,
         ILiteralQualifierTypeCreateParams,
         LiteralQualifierType,
-        LiteralValueHierarchyDecl,
         ILiteralValue,
         ILiteralValueHierarchyCreateParams,
         LiteralValueHierarchy,
@@ -7307,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
@@ -7463,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}.
@@ -7540,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.
      */
@@ -7807,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
@@ -8133,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
      */
@@ -8163,7 +8539,7 @@ declare const resourceName: Converter<ResourceName, unknown>;
  * and caching results for optimal performance.
  * @public
  */
-export declare class ResourceResolver {
+export declare class ResourceResolver implements IResourceResolver {
     /**
      * The resource manager that defines available resources and provides condition access.
      */
@@ -8180,6 +8556,10 @@ export declare class ResourceResolver {
      * The configuration options for this resource resolver.
      */
     readonly options: IResourceResolverOptions;
+    /**
+     * The readonly qualifier collector that provides qualifier implementations.
+     */
+    get qualifiers(): IReadOnlyQualifierCollector;
     /**
      * The cache array for resolved conditions, indexed by condition index for O(1) lookup.
      * Each entry stores the resolved {@link Runtime.IConditionMatchResult | condition match result} for
@@ -8264,6 +8644,15 @@ export declare class ResourceResolver {
      * @public
      */
     resolveResource(resource: IResource): Result<IResourceCandidate>;
+    /**
+     * Resolves a resource by finding the best matching candidate.
+     * Uses the resource's associated decision to determine the best match based on the current context.
+     * @param resource - The string id of the resource to resolve.
+     * @returns `Success` with the best matching candidate if successful,
+     * or `Failure` with an error message if no candidates match or resolution fails.
+     * @public
+     */
+    resolveResource(resource: string): Result<IResourceCandidate>;
     /**
      * Resolves all matching resource candidates in priority order.
      * Uses the resource's associated decision to determine all matching candidates based on the current context.
@@ -8273,6 +8662,15 @@ export declare class ResourceResolver {
      * @public
      */
     resolveAllResourceCandidates(resource: IResource): Result<ReadonlyArray<IResourceCandidate>>;
+    /**
+     * Resolves all matching resource candidates in priority order.
+     * Uses the resource's associated decision to determine all matching candidates based on the current context.
+     * @param resource - The string id of the resource to resolve.
+     * @returns `Success` with an array of all matching candidates in priority order if successful,
+     * or `Failure` with an error message if no candidates match or resolution fails.
+     * @public
+     */
+    resolveAllResourceCandidates(resource: string): Result<ReadonlyArray<IResourceCandidate>>;
     /**
      * 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
@@ -8283,6 +8681,20 @@ export declare class ResourceResolver {
      * @public
      */
     resolveComposedResourceValue(resource: IResource): Result<JsonValue>;
+    /**
+     * 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>;
+    /**
+     * {@inheritDoc IResourceResolver.withContext}
+     */
+    withContext(context: Record<string, string>): Result<ResourceResolver>;
     /**
      * Clears all caches (condition, condition set, and decision), forcing all cached items
      * to be re-evaluated on next access. This should be called when the context changes and cached
@@ -8370,6 +8782,11 @@ declare namespace Resources {
         ICandidateInfo,
         IReducedCandidate,
         CandidateReducer,
+        ICandidateValue,
+        ICandidateValueCreateParams,
+        CandidateValue,
+        ICandidateValueCollectorCreateParams,
+        CandidateValueCollector,
         IResourceCandidateCreateParams,
         ICandidateDeclOptions,
         ResourceCandidate,
@@ -8533,15 +8950,20 @@ declare const resourceTreeRootDecl: Converter<Normalized.IResourceTreeRootDecl>;
  */
 export declare abstract class ResourceType<T = unknown> implements IResourceType<T> {
     private _collectible;
+    private _template;
     /**
      * {@inheritdoc ResourceTypes.IResourceType.key}
      */
     get key(): ResourceTypeName;
+    /**
+     * Name of the underlying system type.
+     */
+    abstract readonly systemTypeName: ResourceTypeName;
     /**
      * {@inheritdoc ResourceTypes.IResourceType.index}
      */
     get index(): ResourceTypeIndex | undefined;
-    protected constructor(key: ResourceTypeName, index?: number);
+    protected constructor(key: ResourceTypeName, index?: number, template?: JsonObject);
     /**
      * Validates properties of a {@link ResourceJson.Json.ILooseResourceCandidateDecl | resource candidate declaration} for
      * a resource instance value.
@@ -8596,16 +9018,20 @@ export declare abstract class ResourceType<T = unknown> implements IResourceType
      * Default implementation provides a basic template.
      * Subclasses can override to provide type-specific templates.
      * @param resourceId - The id for the new resource
+     * @param init - An optional initial value for the resource.
+     * @param conditions - An optional set of conditions that must be met for the resource to be selected.
+     * @param resolver - An optional resource resolver that can be used to create the template.
      * @returns A loose resource declaration with default values for this resource type
      * @public
      */
-    createTemplate(resourceId: ResourceId): ResourceJson.Json.ILooseResourceDecl;
+    createTemplate(resourceId: ResourceId, init?: JsonValue, conditions?: ResourceJson.Json.ConditionSetDecl, resolver?: IResourceResolver): Result<ResourceJson.Json.ILooseResourceDecl>;
     /**
      * Gets the default template value for this resource type.
      * Subclasses should override this to provide type-specific default values.
      * @returns The default JSON value for a new resource of this type
+     * @public
      */
-    protected getDefaultTemplateValue(): JsonObject;
+    getDefaultTemplateCandidate(json?: JsonValue, conditions?: ResourceJson.Json.ConditionSetDecl, __resolver?: IResourceResolver): Result<ResourceJson.Json.IChildResourceCandidateDecl>;
 }
 
 /**
@@ -8982,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.
      */
@@ -9023,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}
      */
@@ -9055,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
@@ -9354,12 +9823,16 @@ declare namespace Validate {
         isValidResourceIndex,
         isValidResourceTypeName,
         isValidResourceTypeIndex,
+        isValidCandidateValueIndex,
+        isValidCandidateValueKey,
         toResourceName,
         toResourceId,
         toOptionalResourceId,
         toResourceIndex,
         toResourceTypeName,
-        toResourceTypeIndex
+        toResourceTypeIndex,
+        toCandidateValueKey,
+        toCandidateValueIndex
     }
 }
 export { Validate }