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

package/lib/packlets/resource-types/jsonResourceType.js

@@ -37,8 +37,8 @@ class JsonResourceType extends resourceType_1.ResourceType {
      * @param key - The key for the new {@link ResourceTypes.JsonResourceType | JsonResourceType} instance.
      * @param index - Optional index for the new {@link ResourceTypes.JsonResourceType | JsonResourceType} instance.
      */
-    constructor(key, index) {
-        super(key, index);
+    constructor(key, index, template) {
+        super(key, index, template);
     }
     /**
      * Factory method to create a new {@link ResourceTypes.JsonResourceType | JsonResourceType} instance.
@@ -49,7 +49,7 @@ class JsonResourceType extends resourceType_1.ResourceType {
     static create(params) {
         var _a;
         return common_1.Convert.resourceTypeName.convert((_a = params === null || params === void 0 ? void 0 : params.key) !== null && _a !== void 0 ? _a : 'json').onSuccess((key) => {
-            return (0, ts_utils_1.captureResult)(() => new JsonResourceType(key, params === null || params === void 0 ? void 0 : params.index));
+            return (0, ts_utils_1.captureResult)(() => new JsonResourceType(key, params === null || params === void 0 ? void 0 : params.index, params === null || params === void 0 ? void 0 : params.template));
         });
     }
     /**
@@ -61,13 +61,6 @@ class JsonResourceType extends resourceType_1.ResourceType {
     validate(json, __completeness) {
         return ts_json_base_1.Converters.jsonObject.convert(json);
     }
-    /**
-     * Gets the default template value for a JSON resource type.
-     * @returns An empty object as the default JSON value
-     */
-    getDefaultTemplateValue() {
-        return {};
-    }
 }
 exports.JsonResourceType = JsonResourceType;
 //# sourceMappingURL=jsonResourceType.js.map

package/lib/packlets/resource-types/resourceType.d.ts

@@ -1,6 +1,6 @@
-import { JsonValue, JsonObject } from '@fgv/ts-json-base';
+import { JsonObject, JsonValue } from '@fgv/ts-json-base';
 import { ICollectible, Result } from '@fgv/ts-utils';
-import { CandidateCompleteness, ResourceTypeIndex, ResourceTypeName, ResourceValueMergeMethod, ResourceId } from '../common';
+import { CandidateCompleteness, ResourceTypeIndex, ResourceTypeName, ResourceValueMergeMethod, ResourceId, IResourceResolver } from '../common';
 import * as ResourceJson from '../resource-json';
 /**
  * Parameters used to validate a {@link ResourceJson.Json.ILooseResourceCandidateDecl | resource candidate declaration}.
@@ -86,11 +86,14 @@ 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>;
 }
 /**
  * Abstract base class for resource types which are responsible for
@@ -100,6 +103,7 @@ export interface IResourceType<T = unknown> extends ICollectible<ResourceTypeNam
  */
 export declare abstract class ResourceType<T = unknown> implements IResourceType<T> {
     private _collectible;
+    private _template;
     /**
      * {@inheritdoc ResourceTypes.IResourceType.key}
      */
@@ -108,7 +112,7 @@ export declare abstract class ResourceType<T = unknown> implements IResourceType
      * {@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.
@@ -163,15 +167,19 @@ 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>;
 }
 //# sourceMappingURL=resourceType.d.ts.map

package/lib/packlets/resource-types/resourceType.js

@@ -22,6 +22,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ResourceType = void 0;
+const ts_json_base_1 = require("@fgv/ts-json-base");
 const ts_utils_1 = require("@fgv/ts-utils");
 const common_1 = require("../common");
 /**
@@ -43,13 +44,14 @@ class ResourceType {
     get index() {
         return this._collectible.index;
     }
-    constructor(key, index) {
+    constructor(key, index, template) {
         this._collectible = new ts_utils_1.Collections.Collectible({
             key,
             /* c8 ignore next 1 - coverage having a rough time */
             index: index !== undefined ? common_1.Validate.toResourceTypeIndex(index).orThrow() : undefined,
             indexConverter: common_1.Convert.resourceTypeIndex
         });
+        this._template = template !== null && template !== void 0 ? template : {};
     }
     /**
      * Sets the index for this resource type.  Once set, the index cannot be changed.
@@ -62,32 +64,34 @@ class ResourceType {
      * 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) {
-        return {
+    createTemplate(resourceId, init, conditions, resolver) {
+        return this.getDefaultTemplateCandidate(init, conditions, resolver).onSuccess((candidate) => (0, ts_utils_1.succeed)({
             id: resourceId,
             resourceTypeName: this.key,
-            candidates: [
-                {
-                    json: this.getDefaultTemplateValue(),
-                    conditions: undefined,
-                    isPartial: false,
-                    mergeMethod: 'replace'
-                }
-            ]
-        };
+            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
      */
-    getDefaultTemplateValue() {
-        // Default implementation returns an empty object
-        // Subclasses should override for type-specific defaults
-        return {};
+    getDefaultTemplateCandidate(json, conditions, __resolver) {
+        json = json !== null && json !== void 0 ? json : this._template;
+        if (!(0, ts_json_base_1.isJsonObject)(json)) {
+            return (0, ts_utils_1.fail)(`${this.key}: Invalid initial value "${json}" must be JSON object.`);
+        }
+        const candidate = Object.assign(Object.assign({ json }, (conditions ? { conditions } : {})), { mergeMethod: 'replace' });
+        return this.validate(json, 'full')
+            .onSuccess((json) => (0, ts_utils_1.succeed)(Object.assign(Object.assign({}, candidate), { isPartial: false })))
+            .onFailure(() => this.validate(json, 'partial').onSuccess((json) => (0, ts_utils_1.succeed)(Object.assign(Object.assign({}, candidate), { isPartial: true }))));
     }
 }
 exports.ResourceType = ResourceType;

package/lib/packlets/runtime/resourceResolver.d.ts

@@ -1,5 +1,6 @@
 import { Result } from '@fgv/ts-utils';
 import { JsonValue } from '@fgv/ts-json-base';
+import { IResourceResolver } from '../common';
 import { Condition, ConditionSet } from '../conditions';
 import { AbstractDecision } from '../decisions';
 import { ReadOnlyQualifierTypeCollector } from '../qualifier-types';
@@ -7,6 +8,7 @@ import { IContextQualifierProvider } from './context';
 import { IResourceManager, IResource, IResourceCandidate } from './iResourceManager';
 import { ConditionSetResolutionResult, IConditionMatchResult } from './conditionSetResolutionResult';
 import { IResourceResolverCacheListener } from './cacheListener';
+import { IReadOnlyQualifierCollector } from '../qualifiers';
 /**
  * Represents the cached result of resolving a decision.
  * Contains either a failure indicator or a list of instance indices for matching condition sets,
@@ -68,7 +70,7 @@ export interface IResourceResolverCreateParams {
  * 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.
      */
@@ -85,6 +87,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
@@ -169,6 +175,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.
@@ -178,6 +193,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
@@ -188,6 +212,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

package/lib/packlets/runtime/resourceResolver.js

@@ -26,6 +26,7 @@ const ts_utils_1 = require("@fgv/ts-utils");
 const ts_json_base_1 = require("@fgv/ts-json-base");
 const ts_json_1 = require("@fgv/ts-json");
 const common_1 = require("../common");
+const context_1 = require("./context");
 const conditionSetResolutionResult_1 = require("./conditionSetResolutionResult");
 /**
  * High-performance runtime resource resolver with O(1) condition caching.
@@ -34,6 +35,12 @@ const conditionSetResolutionResult_1 = require("./conditionSetResolutionResult")
  * @public
  */
 class ResourceResolver {
+    /**
+     * The readonly qualifier collector that provides qualifier implementations.
+     */
+    get qualifiers() {
+        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
@@ -268,15 +275,13 @@ class ResourceResolver {
         (_c = this._listener) === null || _c === void 0 ? void 0 : _c.onCacheMiss('decision', decisionIndex);
         return (0, ts_utils_1.succeed)(successResult);
     }
-    /**
-     * 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 {@link Resources.Resource | 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) {
+    resolveResource(idOrResource) {
+        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;
         // Resolve the decision to get candidate indices in priority order
@@ -301,15 +306,13 @@ class ResourceResolver {
         const bestCandidate = resource.candidates[candidateIndex];
         return (0, ts_utils_1.succeed)(bestCandidate);
     }
-    /**
-     * 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 {@link Resources.Resource | 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) {
+    resolveAllResourceCandidates(idOrResource) {
+        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;
         // Resolve the decision to get candidate indices in priority order
@@ -345,16 +348,13 @@ class ResourceResolver {
         }
         return (0, ts_utils_1.succeed)(candidates);
     }
-    /**
-     * 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 {@link Resources.Resource | 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) {
+    resolveComposedResourceValue(idOrResource) {
+        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) {
@@ -415,6 +415,23 @@ class ResourceResolver {
                 .withErrorFormat((err) => `${resource.id}: Composition failed: ${err}`);
         });
     }
+    /**
+     * {@inheritDoc IResourceResolver.withContext}
+     */
+    withContext(context) {
+        const { resourceManager, qualifierTypes, options } = this;
+        return context_1.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

package/lib/test/unit/resource-types/derivedResourceType.test.d.ts

@@ -0,0 +1,2 @@
+import '@fgv/ts-utils-jest';
+//# sourceMappingURL=derivedResourceType.test.d.ts.map

package/lib/test/unit/resource-types/testDerivedResourceType.d.ts

@@ -0,0 +1,78 @@
+import { JsonObject, JsonValue } from '@fgv/ts-json-base';
+import { Result } from '@fgv/ts-utils';
+import { CandidateCompleteness, ResourceTypeName, ResourceId, IResourceResolver } from '../../../packlets/common';
+import { IResourceCandidateValidationProperties, ResourceType } from '../../../packlets/resource-types/resourceType';
+import * as ResourceJson from '../../../packlets/resource-json';
+/**
+ * Parameters to create a TestDerivedResourceType instance.
+ */
+export interface ITestDerivedResourceTypeCreateParams {
+    /**
+     * Optional key for the new TestDerivedResourceType instance.
+     * Defaults to 'test-derived'.
+     */
+    key?: string;
+    /**
+     * Optional index for the new TestDerivedResourceType instance.
+     */
+    index?: number;
+    /**
+     * Optional template for new instances.
+     */
+    template?: JsonObject;
+    /**
+     * Optional resource ID to use as a template source.
+     * When provided, the resource resolver will be used to look up
+     * this resource and use its value as the template.
+     */
+    templateResourceId?: string;
+}
+/**
+ * Test data structure for the derived resource type
+ */
+export interface ITestData {
+    title: string;
+    description?: string;
+    metadata?: Record<string, JsonValue>;
+}
+/**
+ * Partial test data structure for the derived resource type
+ */
+export interface IPartialTestData {
+    title?: string;
+    description?: string;
+    metadata?: Record<string, JsonValue>;
+}
+/**
+ * A derived resource type for testing that demonstrates:
+ * 1. Custom validation logic
+ * 2. Using a resource resolver to look up template values
+ * 3. Type-specific defaults and error handling
+ */
+export declare class TestDerivedResourceType extends ResourceType<ITestData> {
+    private _templateResourceId?;
+    protected constructor(key: ResourceTypeName, index?: number, template?: JsonObject, templateResourceId?: string);
+    /**
+     * Factory method to create a new TestDerivedResourceType instance.
+     */
+    static create(params?: ITestDerivedResourceTypeCreateParams): Result<TestDerivedResourceType>;
+    /**
+     * Validates a resource candidate declaration with custom logic.
+     */
+    validateDeclaration(props: IResourceCandidateValidationProperties): Result<ITestData | IPartialTestData>;
+    /**
+     * Validates JSON for this resource type with custom business logic.
+     */
+    validate(json: JsonValue, completeness: CandidateCompleteness): Result<IPartialTestData>;
+    validate(json: JsonValue, completeness: 'full'): Result<ITestData>;
+    validate(json: JsonValue, completeness: 'partial'): Result<IPartialTestData>;
+    /**
+     * Override to demonstrate looking up template values from another resource.
+     */
+    getDefaultTemplateCandidate(json?: JsonValue, conditions?: ResourceJson.Json.ConditionSetDecl, resolver?: IResourceResolver): Result<ResourceJson.Json.IChildResourceCandidateDecl>;
+    /**
+     * Override createTemplate to add additional validation for the derived type.
+     */
+    createTemplate(resourceId: ResourceId, init?: JsonValue, conditions?: ResourceJson.Json.ConditionSetDecl, resolver?: IResourceResolver): Result<ResourceJson.Json.ILooseResourceDecl>;
+}
+//# sourceMappingURL=testDerivedResourceType.d.ts.map

package/lib/test/unit/resource-types/testDerivedResourceType.js

@@ -0,0 +1,110 @@
+"use strict";
+/*
+ * Copyright (c) 2025 Erik Fortune
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TestDerivedResourceType = void 0;
+const ts_utils_1 = require("@fgv/ts-utils");
+const common_1 = require("../../../packlets/common");
+// eslint-disable-next-line @rushstack/packlets/mechanics
+const resourceType_1 = require("../../../packlets/resource-types/resourceType");
+/**
+ * A derived resource type for testing that demonstrates:
+ * 1. Custom validation logic
+ * 2. Using a resource resolver to look up template values
+ * 3. Type-specific defaults and error handling
+ */
+class TestDerivedResourceType extends resourceType_1.ResourceType {
+    constructor(key, index, template, templateResourceId) {
+        super(key, index, template);
+        this._templateResourceId = templateResourceId;
+    }
+    /**
+     * Factory method to create a new TestDerivedResourceType instance.
+     */
+    static create(params) {
+        var _a;
+        return common_1.Convert.resourceTypeName.convert((_a = params === null || params === void 0 ? void 0 : params.key) !== null && _a !== void 0 ? _a : 'test-derived').onSuccess((key) => {
+            return (0, ts_utils_1.captureResult)(() => new TestDerivedResourceType(key, params === null || params === void 0 ? void 0 : params.index, params === null || params === void 0 ? void 0 : params.template, params === null || params === void 0 ? void 0 : params.templateResourceId));
+        });
+    }
+    /**
+     * Validates a resource candidate declaration with custom logic.
+     */
+    validateDeclaration(props) {
+        // Custom validation: merge method must be 'replace' for full candidates
+        if (props.completeness === 'full' && props.mergeMethod !== 'replace') {
+            return (0, ts_utils_1.fail)(`${this.key}: Full candidates must use 'replace' merge method, got '${props.mergeMethod}'`);
+        }
+        return this.validate(props.json, props.completeness);
+    }
+    validate(json, completeness) {
+        if (typeof json !== 'object' || json === null || Array.isArray(json)) {
+            return (0, ts_utils_1.fail)(`${this.key}: Expected JSON object, got ${typeof json}`);
+        }
+        const obj = json;
+        // Validate required title field for full resources
+        if (completeness === 'full' && (typeof obj.title !== 'string' || !obj.title.trim())) {
+            return (0, ts_utils_1.fail)(`${this.key}: 'title' field is required and must be a non-empty string`);
+        }
+        // Validate optional description
+        if (obj.description !== undefined && typeof obj.description !== 'string') {
+            return (0, ts_utils_1.fail)(`${this.key}: 'description' field must be a string if provided`);
+        }
+        // Validate optional metadata
+        if (obj.metadata !== undefined) {
+            if (typeof obj.metadata !== 'object' || obj.metadata === null || Array.isArray(obj.metadata)) {
+                return (0, ts_utils_1.fail)(`${this.key}: 'metadata' field must be an object if provided`);
+            }
+        }
+        const result = Object.assign(Object.assign(Object.assign({}, (obj.title && { title: obj.title })), (obj.description && { description: obj.description })), (obj.metadata && { metadata: obj.metadata }));
+        return (0, ts_utils_1.succeed)(result);
+    }
+    /**
+     * Override to demonstrate looking up template values from another resource.
+     */
+    getDefaultTemplateCandidate(json, conditions, resolver) {
+        // If a template resource ID is configured and resolver is available, try to resolve it
+        if (this._templateResourceId && resolver && !json) {
+            return resolver
+                .resolveComposedResourceValue(this._templateResourceId)
+                .onFailure((error) => (0, ts_utils_1.fail)(`${this.key}: Failed to resolve template resource '${this._templateResourceId}': ${error}`))
+                .onSuccess((resolvedValue) => {
+                // Use the resolved value as our JSON template
+                return super.getDefaultTemplateCandidate(resolvedValue, conditions, resolver);
+            });
+        }
+        // Use provided JSON or fall back to base implementation
+        return super.getDefaultTemplateCandidate(json, conditions, resolver);
+    }
+    /**
+     * Override createTemplate to add additional validation for the derived type.
+     */
+    createTemplate(resourceId, init, conditions, resolver) {
+        // Additional validation: warn if trying to use resolver functionality without a resolver
+        if (this._templateResourceId && !resolver) {
+            return (0, ts_utils_1.fail)(`${this.key}: Template resource ID '${this._templateResourceId}' is configured but no resolver provided`);
+        }
+        return super.createTemplate(resourceId, init, conditions, resolver);
+    }
+}
+exports.TestDerivedResourceType = TestDerivedResourceType;
+//# sourceMappingURL=testDerivedResourceType.js.map

package/lib/test/unit/runtime/resourceResolver.coverage.test.d.ts

@@ -0,0 +1,2 @@
+import '@fgv/ts-utils-jest';
+//# sourceMappingURL=resourceResolver.coverage.test.d.ts.map

package/lib/test/unit/runtime/resourceResolver.newFeatures.test.d.ts

@@ -0,0 +1,2 @@
+import '@fgv/ts-utils-jest';
+//# sourceMappingURL=resourceResolver.newFeatures.test.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fgv/ts-res",
-  "version": "5.0.0-21",
+  "version": "5.0.0-22",
   "description": "Multi-dimensional Resource Runtime",
   "main": "lib/index.js",
   "types": "dist/ts-res.d.ts",
@@ -44,16 +44,16 @@
     "@rushstack/heft-node-rig": "~2.9.3",
     "@types/heft-jest": "1.0.6",
     "eslint-plugin-tsdoc": "~0.4.0",
-    "@fgv/ts-utils-jest": "5.0.0-21",
-    "@fgv/ts-extras": "5.0.0-21"
+    "@fgv/ts-utils-jest": "5.0.0-22",
+    "@fgv/ts-extras": "5.0.0-22"
   },
   "dependencies": {
     "luxon": "^3.7.1",
     "fflate": "~0.8.2",
-    "@fgv/ts-utils": "5.0.0-21",
-    "@fgv/ts-json-base": "5.0.0-21",
-    "@fgv/ts-bcp47": "5.0.0-21",
-    "@fgv/ts-json": "5.0.0-21"
+    "@fgv/ts-bcp47": "5.0.0-22",
+    "@fgv/ts-utils": "5.0.0-22",
+    "@fgv/ts-json-base": "5.0.0-22",
+    "@fgv/ts-json": "5.0.0-22"
   },
   "scripts": {
     "build": "heft build --clean",

package/src/packlets/common/resources.ts

@@ -20,7 +20,8 @@
  * SOFTWARE.
  */
 
-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
@@ -76,3 +77,29 @@ export const allResourceValueMergeMethods: ResourceValueMergeMethod[] = ['augmen
  * @public
  */
 export type CandidateCompleteness = 'full' | 'partial';
+
+/**
+ * Minimal resource resolver
+ * @public
+ */
+export 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>;
+}