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

package/src/packlets/resource-types/config/convert.ts

@@ -23,6 +23,7 @@
 /* eslint-disable @rushstack/typedef-var */
 
 import { Converters } from '@fgv/ts-utils';
+import { Converters as JsonConverters } from '@fgv/ts-json-base';
 import { IResourceTypeConfig } from './json';
 
 /**
@@ -32,5 +33,6 @@ import { IResourceTypeConfig } from './json';
  */
 export const resourceTypeConfig = Converters.strictObject<IResourceTypeConfig>({
   name: Converters.string,
-  typeName: Converters.string
+  typeName: Converters.string,
+  template: JsonConverters.jsonObject.optional()
 });

package/src/packlets/resource-types/config/json.ts

@@ -20,6 +20,8 @@
  * SOFTWARE.
  */
 
+import { JsonObject } from '@fgv/ts-json-base';
+
 /**
  * Configuration for a {@link ResourceTypes.ResourceType | resource type}.
  * @public
@@ -27,4 +29,5 @@
 export interface IResourceTypeConfig {
   name: string;
   typeName: string;
+  template?: JsonObject;
 }

package/src/packlets/resource-types/jsonResourceType.ts

@@ -41,6 +41,12 @@ export interface IJsonResourceTypeCreateParams {
    * instance.
    */
   index?: number;
+
+  /**
+   * Optional template for new instances of {@link ResourceTypes.JsonResourceType | JsonResourceType}
+   * resources.
+   */
+  template?: JsonObject;
 }
 
 /**
@@ -54,8 +60,8 @@ export class JsonResourceType extends ResourceType<JsonObject> {
    * @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) {
-    super(key, index);
+  protected constructor(key: ResourceTypeName, index?: number, template?: JsonObject) {
+    super(key, index, template);
   }
 
   /**
@@ -66,7 +72,7 @@ export class JsonResourceType extends ResourceType<JsonObject> {
    */
   public static create(params?: IJsonResourceTypeCreateParams): Result<JsonResourceType> {
     return Convert.resourceTypeName.convert(params?.key ?? 'json').onSuccess((key) => {
-      return captureResult(() => new JsonResourceType(key, params?.index));
+      return captureResult(() => new JsonResourceType(key, params?.index, params?.template));
     });
   }
 
@@ -93,12 +99,4 @@ export class JsonResourceType extends ResourceType<JsonObject> {
   public validate(json: JsonObject, __completeness?: CandidateCompleteness): Result<JsonObject> {
     return JsonConverters.jsonObject.convert(json);
   }
-
-  /**
-   * Gets the default template value for a JSON resource type.
-   * @returns An empty object as the default JSON value
-   */
-  protected getDefaultTemplateValue(): JsonObject {
-    return {};
-  }
 }

package/src/packlets/resource-types/resourceType.ts

@@ -20,8 +20,8 @@
  * SOFTWARE.
  */
 
-import { JsonValue, JsonObject } from '@fgv/ts-json-base';
-import { Collections, ICollectible, Result } from '@fgv/ts-utils';
+import { isJsonObject, JsonObject, JsonValue } from '@fgv/ts-json-base';
+import { Collections, fail, ICollectible, Result, succeed } from '@fgv/ts-utils';
 import {
   CandidateCompleteness,
   Convert as CommonConvert,
@@ -29,7 +29,8 @@ import {
   ResourceTypeIndex,
   ResourceTypeName,
   ResourceValueMergeMethod,
-  ResourceId
+  ResourceId,
+  IResourceResolver
 } from '../common';
 import * as ResourceJson from '../resource-json';
 
@@ -128,11 +129,19 @@ export interface IResourceType<T = unknown> extends ICollectible<ResourceTypeNam
   /**
    * 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>;
 }
 
 /**
@@ -143,6 +152,7 @@ export interface IResourceType<T = unknown> extends ICollectible<ResourceTypeNam
  */
 export abstract class ResourceType<T = unknown> implements IResourceType<T> {
   private _collectible: Collections.Collectible<ResourceTypeName, ResourceTypeIndex>;
+  private _template: JsonObject;
   /**
    * {@inheritdoc ResourceTypes.IResourceType.key}
    */
@@ -157,13 +167,14 @@ export abstract class ResourceType<T = unknown> implements IResourceType<T> {
     return this._collectible.index;
   }
 
-  protected constructor(key: ResourceTypeName, index?: number) {
+  protected constructor(key: ResourceTypeName, index?: number, template?: JsonObject) {
     this._collectible = new Collections.Collectible<ResourceTypeName, ResourceTypeIndex>({
       key,
       /* c8 ignore next 1 - coverage having a rough time */
       index: index !== undefined ? Validate.toResourceTypeIndex(index).orThrow() : undefined,
       indexConverter: CommonConvert.resourceTypeIndex
     });
+    this._template = template ?? {};
   }
 
   /**
@@ -228,32 +239,54 @@ export abstract class ResourceType<T = unknown> implements IResourceType<T> {
    * 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
    */
-  public createTemplate(resourceId: ResourceId): ResourceJson.Json.ILooseResourceDecl {
-    return {
-      id: resourceId,
-      resourceTypeName: this.key,
-      candidates: [
-        {
-          json: this.getDefaultTemplateValue(),
-          conditions: undefined,
-          isPartial: false,
-          mergeMethod: 'replace'
-        }
-      ]
-    };
+  public createTemplate(
+    resourceId: ResourceId,
+    init?: JsonValue,
+    conditions?: ResourceJson.Json.ConditionSetDecl,
+    resolver?: IResourceResolver
+  ): Result<ResourceJson.Json.ILooseResourceDecl> {
+    return this.getDefaultTemplateCandidate(init, conditions, resolver).onSuccess((candidate) =>
+      succeed({
+        id: resourceId,
+        resourceTypeName: this.key,
+        candidates: [candidate]
+      })
+    );
   }
 
   /**
    * 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 {
-    // Default implementation returns an empty object
-    // Subclasses should override for type-specific defaults
-    return {};
+  public getDefaultTemplateCandidate(
+    json?: JsonValue,
+    conditions?: ResourceJson.Json.ConditionSetDecl,
+    __resolver?: IResourceResolver
+  ): Result<ResourceJson.Json.IChildResourceCandidateDecl> {
+    json = json ?? this._template;
+
+    if (!isJsonObject(json)) {
+      return fail(`${this.key}: Invalid initial value "${json}" must be JSON object.`);
+    }
+
+    const candidate: ResourceJson.Json.IChildResourceCandidateDecl = {
+      json,
+      ...(conditions ? { conditions } : {}),
+      mergeMethod: 'replace'
+    };
+
+    return this.validate(json, 'full')
+      .onSuccess((json) => succeed({ ...candidate, isPartial: false }))
+      .onFailure(() =>
+        this.validate(json, 'partial').onSuccess((json) => succeed({ ...candidate, isPartial: true }))
+      );
   }
 }

package/src/packlets/runtime/resourceResolver.ts

@@ -23,11 +23,11 @@
 import { Result, captureResult, fail, succeed } from '@fgv/ts-utils';
 import { JsonValue, JsonObject, isJsonObject } from '@fgv/ts-json-base';
 import { JsonEditor } from '@fgv/ts-json';
-import { NoMatch } from '../common';
+import { IResourceResolver, NoMatch } from '../common';
 import { Condition, ConditionSet } from '../conditions';
 import { AbstractDecision } from '../decisions';
 import { ReadOnlyQualifierTypeCollector } from '../qualifier-types';
-import { IContextQualifierProvider } from './context';
+import { IContextQualifierProvider, ValidatingSimpleContextQualifierProvider } from './context';
 import { IResourceManager, IResource, IResourceCandidate } from './iResourceManager';
 import {
   ConditionMatchType,
@@ -35,6 +35,7 @@ import {
   IConditionMatchResult
 } from './conditionSetResolutionResult';
 import { IResourceResolverCacheListener } from './cacheListener';
+import { IReadOnlyQualifierCollector } from '../qualifiers';
 
 /**
  * Represents the cached result of resolving a decision.
@@ -100,7 +101,7 @@ export interface IResourceResolverCreateParams {
  * and caching results for optimal performance.
  * @public
  */
-export class ResourceResolver {
+export class ResourceResolver implements IResourceResolver {
   /**
    * The resource manager that defines available resources and provides condition access.
    */
@@ -121,6 +122,13 @@ export class ResourceResolver {
    */
   public readonly options: IResourceResolverOptions;
 
+  /**
+   * The readonly qualifier collector that provides qualifier implementations.
+   */
+  public get qualifiers(): IReadOnlyQualifierCollector {
+    return this.contextQualifierProvider.qualifiers;
+  }
+
   /**
    * 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
@@ -412,7 +420,26 @@ export class ResourceResolver {
    * or `Failure` with an error message if no candidates match or resolution fails.
    * @public
    */
-  public resolveResource(resource: IResource): Result<IResourceCandidate> {
+  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
+   */
+  public resolveResource(resource: string): Result<IResourceCandidate>;
+  public resolveResource(idOrResource: string | IResource): Result<IResourceCandidate> {
+    if (typeof idOrResource === 'string') {
+      return this.resourceManager
+        .getBuiltResource(idOrResource)
+        .onSuccess((resource) => this.resolveResource(resource));
+    }
+
+    const resource = idOrResource;
+
     // Get the abstract decision from the resource's concrete decision
     const abstractDecision = resource.decision.baseDecision;
 
@@ -455,7 +482,28 @@ export class ResourceResolver {
    * or `Failure` with an error message if no candidates match or resolution fails.
    * @public
    */
-  public resolveAllResourceCandidates(resource: IResource): Result<ReadonlyArray<IResourceCandidate>> {
+  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
+   */
+  public resolveAllResourceCandidates(resource: string): Result<ReadonlyArray<IResourceCandidate>>;
+  public resolveAllResourceCandidates(
+    idOrResource: string | IResource
+  ): Result<ReadonlyArray<IResourceCandidate>> {
+    if (typeof idOrResource === 'string') {
+      return this.resourceManager
+        .getBuiltResource(idOrResource)
+        .onSuccess((resource) => this.resolveAllResourceCandidates(resource));
+    }
+
+    const resource = idOrResource;
+
     // Get the abstract decision from the resource's concrete decision
     const abstractDecision = resource.decision.baseDecision;
 
@@ -510,7 +558,27 @@ export class ResourceResolver {
    * or `Failure` with an error message if no candidates match or resolution fails.
    * @public
    */
-  public resolveComposedResourceValue(resource: IResource): Result<JsonValue> {
+  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
+   */
+  public resolveComposedResourceValue(resource: string): Result<JsonValue>;
+  public resolveComposedResourceValue(idOrResource: string | IResource): Result<JsonValue> {
+    if (typeof idOrResource === 'string') {
+      return this.resourceManager
+        .getBuiltResource(idOrResource)
+        .onSuccess((resource) => this.resolveComposedResourceValue(resource));
+    }
+
+    const resource = idOrResource;
+
     return this.resolveAllResourceCandidates(resource).onSuccess((candidates) => {
       /* c8 ignore next 3 - defense in depth should never occur */
       if (candidates.length === 0) {
@@ -581,6 +649,24 @@ export class ResourceResolver {
     });
   }
 
+  /**
+   * {@inheritDoc IResourceResolver.withContext}
+   */
+  public withContext(context: Record<string, string>): Result<ResourceResolver> {
+    const { resourceManager, qualifierTypes, options } = this;
+    return ValidatingSimpleContextQualifierProvider.create({
+      qualifiers: this.qualifiers,
+      qualifierValues: context
+    }).onSuccess((contextQualifierProvider) => {
+      return ResourceResolver.create({
+        resourceManager,
+        qualifierTypes,
+        options,
+        contextQualifierProvider
+      });
+    });
+  }
+
   /**
    * 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