@fgv/ts-res 5.0.0-8 → 5.0.1-0

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

@@ -1,5 +1,5 @@
 import { Result } from '@fgv/ts-utils';
-import { ResourceId } from '../common';
+import { ResourceId, ResourceName } from '../common';
 import { ResourceCandidate } from './resourceCandidate';
 import { ResourceType } from '../resource-types';
 import { ConcreteDecision, AbstractDecisionCollector } from '../decisions';
@@ -40,10 +40,14 @@ export declare class Resource implements IResource {
      * The unique {@link ResourceId | id} of the resource.
      */
     readonly id: ResourceId;
+    /**
+     * The name of the resource.
+     */
+    readonly name: ResourceName;
     /**
      * The {@link ResourceTypes.ResourceType | type} of the resource.
      */
-    readonly _resourceType: ResourceType;
+    readonly resourceType: ResourceType;
     /**
      * The array of {@link Resources.ResourceCandidate | candidates} for the resource.
      */
@@ -52,10 +56,6 @@ export declare class Resource implements IResource {
      * {@link Decisions.ConcreteDecision | Decision} for optimized resource resolution.
      */
     readonly decision: ConcreteDecision;
-    /**
-     * Gets the resource type (implements IResource interface).
-     */
-    get resourceType(): ResourceType;
     /**
      * Gets the resource type name as a string.
      */

package/lib/packlets/resources/resource.js

@@ -33,17 +33,11 @@ const decisions_1 = require("../decisions");
  * @public
  */
 class Resource {
-    /**
-     * Gets the resource type (implements IResource interface).
-     */
-    get resourceType() {
-        return this._resourceType;
-    }
     /**
      * Gets the resource type name as a string.
      */
     get resourceTypeName() {
-        return this._resourceType.key;
+        return this.resourceType.key;
     }
     /**
      * Constructor for a {@link Resources.Resource | Resource} object.
@@ -53,7 +47,8 @@ class Resource {
     constructor(params) {
         const id = params.id ? common_1.Validate.toResourceId(params.id).orThrow() : undefined;
         this.id = Resource._validateCandidateResourceIds(id, params.candidates).orThrow();
-        this._resourceType = resourceCandidate_1.ResourceCandidate.validateResourceTypes(params.candidates, params.resourceType)
+        this.name = common_1.Helpers.getNameForResourceId(this.id).orThrow();
+        this.resourceType = resourceCandidate_1.ResourceCandidate.validateResourceTypes(params.candidates, params.resourceType)
             .onSuccess((t) => {
             /* c8 ignore next 3 - functional code path tested but coverage intermittently missed */
             if (t === undefined) {
@@ -120,9 +115,9 @@ class Resource {
      */
     toCompiled(options) {
         const candidates = this._getMatchingCandidates(options).map((c) => ({
-            json: c.json,
             isPartial: c.isPartial,
-            mergeMethod: c.mergeMethod
+            mergeMethod: c.mergeMethod,
+            valueIndex: c.candidateValue.index
         }));
         return {
             id: this.id,

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

@@ -5,6 +5,7 @@ import { ReadOnlyResourceTypeCollector, ResourceType } from '../resource-types';
 import { Resource } from './resource';
 import { ConditionSetCollector } from '../conditions';
 import { AbstractDecisionCollector } from '../decisions';
+import { CandidateValueCollector } from './candidateValueCollector';
 import * as ResourceJson from '../resource-json';
 import * as Context from '../context';
 /**
@@ -17,6 +18,7 @@ export interface IResourceBuilderCreateParams {
     conditionSets: ConditionSetCollector;
     resourceTypes: ReadOnlyResourceTypeCollector;
     decisions: AbstractDecisionCollector;
+    candidateValues: CandidateValueCollector;
 }
 /**
  * Possible result details returned by the resource builder
@@ -66,6 +68,10 @@ export 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}.

package/lib/packlets/resources/resourceBuilder.js

@@ -56,6 +56,7 @@ class ResourceBuilder {
         this._resourceTypes = params.resourceTypes;
         this._conditionSets = params.conditionSets;
         this._decisions = params.decisions;
+        this._candidateValues = params.candidateValues;
         this._candidates = new ts_utils_1.ResultMap();
         if (params.typeName) {
             this._resourceType = this._resourceTypes.validating.get(params.typeName).orThrow();
@@ -93,7 +94,8 @@ class ResourceBuilder {
             id: this.id,
             resourceType: this._resourceType,
             decl: childDecl,
-            conditionSets: this._conditionSets
+            conditionSets: this._conditionSets,
+            candidateValues: this._candidateValues
         })
             .withDetail('failure', 'success')
             .onSuccess((candidate) => {
@@ -101,6 +103,7 @@ class ResourceBuilder {
                 .getOrAdd(candidate.conditions.toString(), candidate)
                 .onSuccess((added, detail) => {
                 if (detail === 'exists') {
+                    /* c8 ignore next 5 - defensive coding: conflicting candidates with same conditions should not occur */
                     if (!resourceCandidate_1.ResourceCandidate.equal(added, candidate)) {
                         return (0, ts_utils_1.failWithDetail)(`${this.id}: conflicting candidates.`, 'exists');
                     }

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

@@ -1,8 +1,10 @@
 import { JsonObject } from '@fgv/ts-json-base';
-import { QualifierName, ResourceId, ResourceValueMergeMethod } from '../common';
+import { CandidateCompleteness, QualifierName, ResourceId, ResourceValueMergeMethod } from '../common';
 import { Condition, ConditionSet, ConditionSetCollector } from '../conditions';
 import * as ResourceJson from '../resource-json';
 import { ResourceType } from '../resource-types';
+import { CandidateValue } from './candidateValue';
+import { CandidateValueCollector } from './candidateValueCollector';
 import { Result } from '@fgv/ts-utils';
 import * as Context from '../context';
 import { IResourceCandidate } from '../runtime';
@@ -16,6 +18,7 @@ export interface IResourceCandidateCreateParams {
     resourceType?: ResourceType;
     parentConditions?: ReadonlyArray<Condition>;
     conditionSets: ConditionSetCollector;
+    candidateValues: CandidateValueCollector;
 }
 /**
  * Options for creating a {@link Resources.ResourceCandidate | ResourceCandidate} declaration.
@@ -43,10 +46,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.
      */
@@ -64,6 +73,10 @@ export declare class ResourceCandidate implements IResourceCandidate {
      * this candidate belongs.
      */
     readonly resourceType: ResourceType | undefined;
+    /**
+     * The completeness of the candidate value.
+     */
+    get completeness(): CandidateCompleteness;
     /**
      * Constructor for a {@link Resources.ResourceCandidate | ResourceCandidate} object.
      * @param params - Parameters to create a new {@link Resources.ResourceCandidate | ResourceCandidate}.

package/lib/packlets/resources/resourceCandidate.js

@@ -66,6 +66,20 @@ const ts_utils_1 = require("@fgv/ts-utils");
  * @public
  */
 class ResourceCandidate {
+    /**
+     * The JSON representation of the instance data to be applied.
+     * @remarks
+     * This property provides access to the JSON data from the underlying candidate value.
+     */
+    get json() {
+        return this.candidateValue.json;
+    }
+    /**
+     * The completeness of the candidate value.
+     */
+    get completeness() {
+        return this.isPartial ? 'partial' : 'full';
+    }
     /**
      * Constructor for a {@link Resources.ResourceCandidate | ResourceCandidate} object.
      * @param params - Parameters to create a new {@link Resources.ResourceCandidate | ResourceCandidate}.
@@ -74,7 +88,7 @@ class ResourceCandidate {
     constructor(params) {
         var _a, _b;
         this.id = common_1.Validate.toResourceId(params.id).orThrow();
-        this.json = params.decl.json;
+        this.candidateValue = params.candidateValues.validating.getOrAdd(params.decl.json).orThrow();
         this.conditions = ResourceCandidate._mergeConditions(params.conditionSets, params.decl.conditions, params.parentConditions).orThrow();
         this.isPartial = (_a = params.decl.isPartial) !== null && _a !== void 0 ? _a : false;
         this.mergeMethod = (_b = params.decl.mergeMethod) !== null && _b !== void 0 ? _b : 'augment';
@@ -175,10 +189,8 @@ class ResourceCandidate {
             rc1.mergeMethod === rc2.mergeMethod &&
             conditions_1.ConditionSet.compare(rc1.conditions, rc2.conditions) === 0;
         if (equal) {
-            const normalizer = new ts_utils_1.Hash.Crc32Normalizer();
-            const n1 = normalizer.computeHash(rc1.json).orDefault('(n1 normalization failed)');
-            const n2 = normalizer.computeHash(rc2.json).orDefault('(n2 normalization failed)');
-            equal = n1 === n2;
+            // Compare candidate values by their keys for efficient JSON comparison
+            equal = rc1.candidateValue.key === rc2.candidateValue.key;
         }
         return equal;
     }

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

@@ -1,17 +1,19 @@
 import { Collections, DetailedResult, Result, ValidatingResultMap } from '@fgv/ts-utils';
-import { ConditionCollector, ConditionSetCollector, ReadOnlyConditionCollector, ReadOnlyConditionSetCollector } from '../conditions';
+import { ConditionCollector, ConditionSetCollector, ReadOnlyConditionCollector, ReadOnlyConditionSetCollector, Condition, ConditionSet } from '../conditions';
 import { AbstractDecisionCollector, ReadOnlyAbstractDecisionCollector } from '../decisions';
 import { IReadOnlyQualifierCollector } from '../qualifiers';
 import { ReadOnlyResourceTypeCollector } from '../resource-types';
 import { ResourceId } from '../common';
-import { IResourceManager } from '../runtime';
+import { IResourceManager, ResourceTree } from '../runtime';
 import { ResourceBuilder, ResourceBuilderResultDetail } from './resourceBuilder';
 import { Resource } from './resource';
 import { ResourceCandidate } from './resourceCandidate';
+import { CandidateValueCollector } from './candidateValueCollector';
 import { IResourceDeclarationOptions, IResourceManagerCloneOptions } from './common';
 import * as ResourceJson from '../resource-json';
 import * as Context from '../context';
 import * as Config from '../config';
+import { ReadOnlyQualifierTypeCollector } from '../qualifier-types';
 /**
  * Interface for parameters to the {@link Resources.ResourceManagerBuilder.create | ResourceManagerBuilder create method}.
  * @public
@@ -32,15 +34,59 @@ export type ResourceManagerBuilderResultDetail = Collections.ResultMapResultDeta
  * and builds a collection of {@link Resources.Resource | resources} once all candidates are collected.
  * @public
  */
-export declare class ResourceManagerBuilder implements IResourceManager {
+export declare class ResourceManagerBuilder implements IResourceManager<Resource> {
+    /**
+     * The {@link Qualifiers.IReadOnlyQualifierCollector | qualifiers} used by this resource manager.
+     */
     readonly qualifiers: IReadOnlyQualifierCollector;
+    /**
+     * The {@link ResourceTypes.ReadOnlyResourceTypeCollector | resource types} used by this resource manager.
+     */
     readonly resourceTypes: ReadOnlyResourceTypeCollector;
+    /**
+     * The {@link Conditions.ConditionCollector | condition collector} used by this resource manager.
+     * @internal
+     */
     protected readonly _conditions: ConditionCollector;
+    /**
+     * The {@link Conditions.ConditionSetCollector | condition set collector} used by this resource manager.
+     * @internal
+     */
     protected readonly _conditionSets: ConditionSetCollector;
+    /**
+     * The {@link Decisions.AbstractDecisionCollector | abstract decision collector} used by this resource manager.
+     * @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
+     */
     protected readonly _resources: ValidatingResultMap<ResourceId, ResourceBuilder>;
-    readonly _builtResources: ValidatingResultMap<ResourceId, Resource>;
+    /**
+     * The {@link Resources.Resource | resources} built by this resource manager.
+     * @internal
+     */
+    protected readonly _builtResources: ValidatingResultMap<ResourceId, Resource>;
+    /**
+     * Whether the resources have been built.
+     * @internal
+     */
     protected _built: boolean;
+    /**
+     * The cached resource tree for this resource manager.
+     * @internal
+     */
+    protected _cachedResourceTree?: ResourceTree.IReadOnlyResourceTreeRoot<Resource>;
+    /**
+     * The {@link QualifierTypes.ReadOnlyQualifierTypeCollector | qualifier types} used by this resource manager.
+     */
+    get qualifierTypes(): ReadOnlyQualifierTypeCollector;
     /**
      * A {@link Conditions.ConditionCollector | ConditionCollector} which
      * contains the {@link Conditions.Condition | conditions} used so far by
@@ -106,6 +152,17 @@ export declare class ResourceManagerBuilder implements IResourceManager {
      * @public
      */
     static createPredefined(name: Config.PredefinedSystemConfiguration, qualifierDefaultValues?: Config.ISystemConfigurationInitParams['qualifierDefaultValues']): Result<ResourceManagerBuilder>;
+    /**
+     * Creates a new {@link Resources.ResourceManagerBuilder | ResourceManagerBuilder} from a
+     * {@link ResourceJson.Compiled.ICompiledResourceCollection | compiled resource collection}.
+     * This method reconstructs an exactly equivalent builder where all qualifier, condition,
+     * condition set, and decision indices match the original compiled collection.
+     * @param compiledCollection - The compiled resource collection to reconstruct from.
+     * @param systemConfig - The system configuration containing qualifiers and resource types.
+     * @returns `Success` with the new manager if successful, or `Failure` with an error message if not.
+     * @public
+     */
+    static createFromCompiledResourceCollection(compiledCollection: ResourceJson.Compiled.ICompiledResourceCollection, systemConfig: Config.SystemConfiguration): Result<ResourceManagerBuilder>;
     /**
      * Given a {@link ResourceJson.Json.ILooseResourceCandidateDecl | resource candidate declaration}, builds and adds
      * a {@link Resources.ResourceCandidate | candidate} to the manager.
@@ -115,6 +172,20 @@ export declare class ResourceManagerBuilder implements IResourceManager {
      */
     addLooseCandidate(decl: ResourceJson.Json.ILooseResourceCandidateDecl): DetailedResult<ResourceCandidate, ResourceBuilderResultDetail>;
     addResource(decl: ResourceJson.Json.ILooseResourceDecl): DetailedResult<ResourceBuilder, ResourceBuilderResultDetail>;
+    /**
+     * Adds a condition to the manager.
+     * @param decl - The condition declaration to add.
+     * @returns `Success` with the condition if successful, or `Failure` with an error message if not.
+     * @public
+     */
+    addCondition(decl: ResourceJson.Json.ILooseConditionDecl): Result<Condition>;
+    /**
+     * Adds a condition set to the manager.
+     * @param decl - The condition set declaration to add.
+     * @returns `Success` with the condition set if successful, or `Failure` with an error message if not.
+     * @public
+     */
+    addConditionSet(conditions: ResourceJson.Normalized.ConditionSetDecl): Result<ConditionSet>;
     /**
      * Gets a read-only array of all {@link Resources.ResourceBuilder | resource builders} present in the manager.
      * @returns `Success` with the {@link Resources.ResourceBuilder | resource builder} if successful,
@@ -145,6 +216,19 @@ export declare class ResourceManagerBuilder implements IResourceManager {
      * @public
      */
     getAllBuiltResources(): Result<ReadonlyArray<Resource>>;
+    /**
+     * Builds and returns a hierarchical tree representation of all resources managed by this builder.
+     * Resources are organized based on their dot-separated resource IDs (e.g., "app.messages.welcome"
+     * becomes a tree with "app" as root, "messages" as branch, and "welcome" as leaf).
+     *
+     * String-based validation is available through the `children.validating` property,
+     * allowing callers to use `tree.children.validating.getById(stringId)` for validated access.
+     *
+     * Uses lazy initialization with caching for performance.
+     * @returns Result containing the resource tree root, or failure if tree construction fails
+     * @public
+     */
+    getBuiltResourceTree(): Result<ResourceTree.IReadOnlyResourceTreeRoot<Resource>>;
     /**
      * Gets a read-only array of all {@link Resources.Resource | built resources} in the manager.
      * @returns `Success` with an array of resources if successful, or `Failure` with an error message if not.
@@ -218,12 +302,17 @@ export declare class ResourceManagerBuilder implements IResourceManager {
      */
     getResourceCollectionDecl(options?: IResourceDeclarationOptions): Result<ResourceJson.Normalized.IResourceCollectionDecl>;
     /**
-     * Creates a filtered clone of this ResourceManagerBuilder using the specified context.
-     * This is a convenience method that creates a new ResourceManagerBuilder with the same
-     * configuration but filtered to include only candidates that match the provided context.
-     * If candidates are provided for editing, they will be applied with collision detection.
-     * @param options - Options for the cloning operation, including the strongly-typed filterForContext property and optional candidates for edits.
-     * @returns A Result containing the new filtered ResourceManagerBuilder.
+     * Creates a clone of this ResourceManagerBuilder with optional configuration overrides.
+     * This method creates a new ResourceManagerBuilder that can optionally use different
+     * qualifiers and/or resource types than the original. It can also be filtered to include
+     * only candidates that match the provided context and apply candidate edits.
+     *
+     * @param options - Options for the cloning operation:
+     *   - `qualifiers`: Optional qualifier collector to use instead of the original
+     *   - `resourceTypes`: Optional resource type collector to use instead of the original
+     *   - `filterForContext`: Optional context filter for candidates
+     *   - `candidates`: Optional candidate edits to apply during cloning
+     * @returns A Result containing the new ResourceManagerBuilder with the specified configuration.
      * @public
      */
     clone(options?: IResourceManagerCloneOptions): Result<ResourceManagerBuilder>;
@@ -242,7 +331,6 @@ export declare class ResourceManagerBuilder implements IResourceManager {
      * @returns A Result containing the ConditionSet token if successful, or failure if validation fails
      * @internal
      */
-    private static _getConditionSetToken;
     /**
      * Applies candidate edits to a resource declaration, handling collisions using condition set tokens.
      * If there's no collision, adds the candidate. If there's a collision, replaces the original candidate with the edit.
@@ -263,5 +351,48 @@ export declare class ResourceManagerBuilder implements IResourceManager {
      * @internal
      */
     private static _createResourceDeclFromCandidates;
+    /**
+     * Reconstructs conditions from a compiled collection and adds them to the builder.
+     * @param builder - The builder to add conditions to.
+     * @param compiledCollection - The compiled collection containing conditions.
+     * @returns `Success` if all conditions were added successfully, `Failure` otherwise.
+     * @internal
+     */
+    private static _reconstructConditions;
+    /**
+     * Reconstructs condition sets from a compiled collection and adds them to the builder.
+     * @param builder - The builder to add condition sets to.
+     * @param compiledCollection - The compiled collection containing condition sets.
+     * @returns `Success` if all condition sets were added successfully, `Failure` otherwise.
+     * @internal
+     */
+    private static _reconstructConditionSets;
+    /**
+     * Reconstructs decisions from a compiled collection and adds them to the builder.
+     * @param builder - The builder to add decisions to.
+     * @param compiledCollection - The compiled collection containing decisions.
+     * @returns `Success` if all decisions were added successfully, `Failure` otherwise.
+     * @internal
+     */
+    private static _reconstructDecisions;
+    /**
+     * Reconstructs resources and their candidates from a compiled collection and adds them to the builder.
+     * @param builder - The builder to add resources to.
+     * @param compiledCollection - The compiled collection containing resources.
+     * @returns `Success` if all resources were added successfully, `Failure` otherwise.
+     * @internal
+     */
+    private static _reconstructResources;
+    /**
+     * Helper method to create candidates from a decision's condition sets.
+     * @param compiledResource - The compiled resource containing candidates.
+     * @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
+     */
+    private static _createCandidatesFromDecision;
 }
 //# sourceMappingURL=resourceManagerBuilder.d.ts.map