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

package/src/packlets/resources/resource.ts

@@ -0,0 +1,307 @@
+/*
+ * 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.
+ */
+
+import { MessageAggregator, Result, captureResult, fail, succeed } from '@fgv/ts-utils';
+import { Helpers, ResourceId, ResourceName, Validate } from '../common';
+import { ResourceCandidate } from './resourceCandidate';
+import { CandidateReducer } from './candidateReducer';
+import { ResourceType } from '../resource-types';
+import { ConcreteDecision, AbstractDecisionCollector } from '../decisions';
+import { IResource } from '../runtime';
+import { IResourceDeclarationOptions, ICompiledResourceOptionsWithFilter } from './common';
+import * as ResourceJson from '../resource-json';
+import * as Context from '../context';
+
+/**
+ * Parameters used to create a {@link Resources.Resource | Resource} object.
+ * @public
+ */
+export interface IResourceCreateParams {
+  /**
+   * The id of the resource.
+   */
+  id?: string;
+  /**
+   * Optional {@link ResourceTypes.ResourceType | type} of the resource. If not specified, the type will be inferred
+   * from the candidates.
+   */
+  resourceType?: ResourceType;
+  /**
+   * Array of {@link Resources.ResourceCandidate | candidates} for the resource.
+   */
+  candidates: ReadonlyArray<ResourceCandidate>;
+  /**
+   * {@link Decisions.AbstractDecisionCollector | AbstractDecisionCollector} used to create the optimized decision.
+   */
+  decisions: AbstractDecisionCollector;
+}
+
+/**
+ * Represents a single logical resource, with a unique id and a set of possible
+ * candidate instances.
+ * @public
+ */
+export class Resource implements IResource {
+  /**
+   * The unique {@link ResourceId | id} of the resource.
+   */
+  public readonly id: ResourceId;
+
+  /**
+   * The name of the resource.
+   */
+  public readonly name: ResourceName;
+
+  /**
+   * The {@link ResourceTypes.ResourceType | type} of the resource.
+   */
+  public readonly resourceType: ResourceType;
+
+  /**
+   * The array of {@link Resources.ResourceCandidate | candidates} for the resource.
+   */
+  public readonly candidates: ReadonlyArray<ResourceCandidate>;
+  /**
+   * {@link Decisions.ConcreteDecision | Decision} for optimized resource resolution.
+   */
+  public readonly decision: ConcreteDecision;
+
+  /**
+   * Gets the resource type name as a string.
+   */
+  public get resourceTypeName(): string {
+    return this.resourceType.key;
+  }
+
+  /**
+   * Constructor for a {@link Resources.Resource | Resource} object.
+   * @param params - {@link Resources.IResourceCreateParams | Parameters} used to create the resource.
+   * @public
+   */
+  protected constructor(params: IResourceCreateParams) {
+    const id = params.id ? Validate.toResourceId(params.id).orThrow() : undefined;
+    this.id = Resource._validateCandidateResourceIds(id, params.candidates).orThrow();
+    this.name = Helpers.getNameForResourceId(this.id).orThrow();
+    this.resourceType = ResourceCandidate.validateResourceTypes(params.candidates, params.resourceType)
+      .onSuccess((t) => {
+        /* c8 ignore next 3 - functional code path tested but coverage intermittently missed */
+        if (t === undefined) {
+          return fail<ResourceType>(`${params.id}: no type specified and no candidates with types.`);
+        }
+        return succeed(t);
+      })
+      .orThrow();
+
+    this.candidates = Resource._validateAndNormalizeCandidates(params.candidates).orThrow();
+    this.decision = Resource._createOptimizedDecision(this.candidates, params.decisions).orThrow();
+  }
+
+  /**
+   * Creates a new {@link Resources.Resource | Resource} object.
+   * @param params - {@link Resources.IResourceCreateParams | Parameters} used to create the resource.
+   * @returns `Success` with the new {@link Resources.Resource | Resource} object if successful,
+   * or `Failure` with an error message if not.
+   * @public
+   */
+  public static create(params: IResourceCreateParams): Result<Resource> {
+    return captureResult(() => new Resource(params));
+  }
+
+  /**
+   * Gets the candidates for this resource that match the specified {@link Context.IValidatedContextDecl | context}.
+   * @param context - The {@link Context.IValidatedContextDecl | context} to match against.
+   * @param options - {@link Context.IContextMatchOptions | options} for the context match.
+   * @returns The array of {@link Resources.ResourceCandidate | candidates} that match the context.
+   */
+  public getCandidatesForContext(
+    context: Context.IValidatedContextDecl,
+    options?: Context.IContextMatchOptions
+  ): ReadonlyArray<ResourceCandidate> {
+    return this.candidates.filter((c) => c.canMatchPartialContext(context, options));
+  }
+
+  /**
+   * Gets the {@link ResourceJson.Json.IChildResourceDecl | child resource declaration} for this resource.
+   * @param options - {@link ResourceJson.Helpers.IDeclarationOptions | options} for the declaration.
+   * @returns The {@link ResourceJson.Json.IChildResourceDecl | child resource declaration}.
+   */
+  public toChildResourceDecl(options?: IResourceDeclarationOptions): ResourceJson.Json.IChildResourceDecl {
+    /* c8 ignore next 1 - defense in depth */
+    options = options ?? {};
+    const matches = this._getMatchingCandidates(options);
+
+    const candidates = options.reduceQualifiers
+      ? CandidateReducer.reduceToChildResourceCandidateDecls(matches, options.filterForContext).orThrow()
+      : matches.map((c) => c.toChildResourceCandidateDecl());
+
+    return {
+      resourceTypeName: this.resourceTypeName,
+      ...(candidates.length > 0 ? { candidates } : {})
+    };
+  }
+
+  /**
+   * Gets the {@link ResourceJson.Json.ILooseResourceDecl | loose resource declaration} for this resource.
+   * @param options - {@link Resources.IResourceDeclarationOptions | options} for the declaration.
+   * @returns The {@link ResourceJson.Json.ILooseResourceDecl | loose resource declaration}.
+   */
+  public toLooseResourceDecl(options?: IResourceDeclarationOptions): ResourceJson.Json.ILooseResourceDecl {
+    /* c8 ignore next 1 - defense in depth */
+    options = options ?? {};
+    const matches = this._getMatchingCandidates(options);
+
+    const candidates = options.reduceQualifiers
+      ? CandidateReducer.reduceToChildResourceCandidateDecls(matches, options.filterForContext).orThrow()
+      : matches.map((c) => c.toChildResourceCandidateDecl());
+
+    return {
+      id: this.id,
+      resourceTypeName: this.resourceTypeName,
+      ...(candidates.length > 0 ? { candidates } : {})
+    };
+  }
+
+  /**
+   * Converts this resource to a compiled resource representation.
+   * @param options - Optional compilation options controlling the output format and filtering.
+   * @returns A compiled resource object that can be used for serialization or runtime processing.
+   * @public
+   */
+  public toCompiled(
+    options?: IResourceDeclarationOptions | ICompiledResourceOptionsWithFilter
+  ): ResourceJson.Compiled.ICompiledResource {
+    const candidates: ResourceJson.Compiled.ICompiledCandidate[] = this._getMatchingCandidates(options).map(
+      (c) => ({
+        json: c.json,
+        isPartial: c.isPartial,
+        mergeMethod: c.mergeMethod
+      })
+    );
+
+    return {
+      id: this.id,
+      type: this.resourceType.index!,
+      decision: this.decision.baseDecision.index!,
+      candidates
+    };
+  }
+
+  /**
+   * Validates that all candidates have the same id as the resource.
+   * @param resourceId - The expected id of the resource.
+   * @param candidates - The array of candidates to validate.
+   * @returns `Success` with the resource id if all candidates have the same id,
+   * `Failure` with an error message otherwise.
+   * @internal
+   */
+  private static _validateCandidateResourceIds(
+    resourceId: ResourceId | undefined,
+    candidates: ReadonlyArray<ResourceCandidate>
+  ): Result<ResourceId> {
+    /* c8 ignore next 3 - functional code path tested but coverage intermittently missed */
+    if (!resourceId && candidates.length === 0) {
+      return fail('unknown: no resource id and no candidates.');
+    }
+    resourceId = resourceId ?? candidates[0].id;
+
+    const mismatched = candidates.filter((c) => c.id !== resourceId).map((c) => c.id);
+    /* c8 ignore next 3 - functional code path tested but coverage intermittently missed */
+    if (mismatched.length > 0) {
+      return fail(`${resourceId}: candidates with mismatched ids ${mismatched.join(', ')}.`);
+    }
+    return succeed(resourceId);
+  }
+
+  /**
+   * Creates an optimized decision for the given candidates using the decisions collector.
+   * @param candidates - The validated and normalized candidates to create a decision for.
+   * @param decisions - The {@link Decisions.AbstractDecisionCollector | AbstractDecisionCollector} to use.
+   * @returns `Success` with the {@link Decisions.ConcreteDecision | ConcreteDecision} if successful,
+   * `Failure` with an error message otherwise.
+   * @internal
+   */
+  private static _createOptimizedDecision(
+    candidates: ReadonlyArray<ResourceCandidate>,
+    decisions: AbstractDecisionCollector
+  ): Result<ConcreteDecision> {
+    const decisionCandidates = candidates.map((c) => ({
+      conditionSet: c.conditions,
+      value: c.json
+    }));
+
+    return ConcreteDecision.create({
+      decisions,
+      candidates: decisionCandidates
+    });
+  }
+
+  /**
+   * Validates and normalizes an array of {@link Resources.ResourceCandidate | candidates}. Fails if there
+   * are multiple candidates for the same set of conditions.
+   * @param candidates - The array of candidates to validate.
+   * @returns `Success` with the validated and sorted array of candidates if successful,
+   * `Failure` with an error message otherwise.
+   * @internal
+   */
+  private static _validateAndNormalizeCandidates(
+    candidates: ReadonlyArray<ResourceCandidate>
+  ): Result<ReadonlyArray<ResourceCandidate>> {
+    const errors = new MessageAggregator();
+    const validated: Map<string, ResourceCandidate> = new Map();
+
+    for (const candidate of candidates) {
+      const conditionSetString = candidate.conditions.toString();
+      const existing = validated.get(conditionSetString);
+      if (existing) {
+        /* c8 ignore next 3 - functional code path tested but coverage intermittently missed */
+        if (!ResourceCandidate.equal(candidate, existing)) {
+          errors.addMessage(`${candidate.id}: duplicate candidates for ${conditionSetString}.`);
+        }
+      } else {
+        validated.set(conditionSetString, candidate);
+      }
+    }
+    return errors.returnOrReport(
+      succeed(Array.from(validated.values()).sort(ResourceCandidate.compare).reverse())
+    );
+  }
+
+  /**
+   * Gets the appropriate candidates based on filtering options.
+   * If a validated filter context is provided, returns only matching candidates.
+   * Otherwise returns all candidates.
+   * @param options - Options that may contain a validated filter context
+   * @returns The filtered array of candidates
+   * @internal
+   */
+  protected _getMatchingCandidates(
+    options?: IResourceDeclarationOptions | ICompiledResourceOptionsWithFilter
+  ): ReadonlyArray<ResourceCandidate> {
+    /* c8 ignore next 5 - functional code path tested but coverage intermittently missed */
+    if (options?.filterForContext) {
+      return this.candidates.filter((candidate) =>
+        candidate.canMatchPartialContext(options.filterForContext!, { partialContextMatch: true })
+      );
+    }
+    return this.candidates;
+  }
+}

package/src/packlets/resources/resourceBuilder.ts

@@ -0,0 +1,269 @@
+/*
+ * 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.
+ */
+
+import {
+  Collections,
+  DetailedResult,
+  Result,
+  ResultMap,
+  captureResult,
+  fail,
+  failWithDetail,
+  succeed,
+  succeedWithDetail
+} from '@fgv/ts-utils';
+import { ResourceId, Validate } from '../common';
+import { ResourceCandidate } from './resourceCandidate';
+import { ReadOnlyResourceTypeCollector, ResourceType } from '../resource-types';
+import { Resource } from './resource';
+import { ConditionSetCollector } from '../conditions';
+import { AbstractDecisionCollector } from '../decisions';
+import * as ResourceJson from '../resource-json';
+import * as Context from '../context';
+
+/**
+ * Parameters for creating a {@link Resources.ResourceBuilder}.
+ * @public
+ */
+export interface IResourceBuilderCreateParams {
+  id: string;
+  typeName?: string;
+  conditionSets: ConditionSetCollector;
+  resourceTypes: ReadOnlyResourceTypeCollector;
+  decisions: AbstractDecisionCollector;
+}
+
+/**
+ * Possible result details returned by the resource builder
+ * {@link Resources.ResourceBuilder.addLooseCandidate | addLooseCandidate} method.
+ * @public
+ */
+export type ResourceBuilderResultDetail = Collections.ResultMapResultDetail | 'id-mismatch' | 'type-mismatch';
+
+/**
+ * Represents a builder for a single logical {@link Resources.Resource | resource}.  Collects candidates
+ * with a common resource ID, validates them against each other and builds a {@link Resources.Resource | resource}
+ * object once all candidates are collected.
+ * @public
+ */
+export class ResourceBuilder {
+  /**
+   * The unique {@link ResourceId | id} of the resource being built.
+   */
+  public readonly id: ResourceId;
+
+  /**
+   * Supplied or inferred {@link ResourceTypes.ResourceType | type} of the resource being built.
+   * If no type is supplied, the type will be inferred from the candidates - at least one candidate must
+   * define resource type and all candidates must be of the same type.
+   */
+  public get resourceType(): ResourceType | undefined {
+    return this._resourceType;
+  }
+
+  /**
+   * Array of {@link Resources.ResourceCandidate | candidates} for the resource being built.
+   */
+  public get candidates(): ReadonlyArray<ResourceCandidate> {
+    return Array.from(this._candidates.values()).sort(ResourceCandidate.compare).reverse();
+  }
+
+  /**
+   * The supplied or inferred {@link ResourceTypes.ResourceType | type} of the resource
+   * being built.
+   */
+  protected _resourceType: ResourceType | undefined;
+
+  /**
+   * Map of {@link Resources.ResourceCandidate | candidates} for the resource being built.
+   */
+  protected _candidates: ResultMap<string, ResourceCandidate>;
+
+  /**
+   * Map of all known {@link ResourceTypes.ResourceType | resource types}.
+   */
+  protected _resourceTypes: ReadOnlyResourceTypeCollector;
+
+  /**
+   * Common collector for {@link Conditions.ConditionSet | condition sets}.
+   */
+  protected _conditionSets: ConditionSetCollector;
+
+  /**
+   * Collector for {@link Decisions.AbstractDecision | abstract decisions}.
+   */
+  protected _decisions: AbstractDecisionCollector;
+
+  /**
+   * Constructor for a {@link Resources.ResourceBuilder | ResourceBuilder} object.
+   * @param params - Parameters to construct the new {@link Resources.ResourceBuilder | ResourceBuilder}.
+   */
+  protected constructor(params: IResourceBuilderCreateParams) {
+    this.id = Validate.toResourceId(params.id).orThrow();
+    this._resourceTypes = params.resourceTypes;
+    this._conditionSets = params.conditionSets;
+    this._decisions = params.decisions;
+    this._candidates = new ResultMap<string, ResourceCandidate>();
+    if (params.typeName) {
+      this._resourceType = this._resourceTypes.validating.get(params.typeName).orThrow();
+    }
+  }
+
+  /**
+   * Creates a new {@link Resources.ResourceBuilder | ResourceBuilder} object.
+   * @param params - Parameters to create a new {@link Resources.ResourceBuilder | ResourceBuilder}.
+   * @returns `Success` with the new {@link Resources.ResourceBuilder | ResourceBuilder} object if successful,
+   * or `Failure` with an error message if not.
+   * @public
+   */
+  public static create(params: IResourceBuilderCreateParams): Result<ResourceBuilder> {
+    return captureResult(() => new ResourceBuilder(params));
+  }
+
+  /**
+   * Gets the {@link Resources.ResourceCandidate | candidates} that match a given {@link Context.IValidatedContextDecl | context}.
+   * @param context - The {@link Context.IValidatedContextDecl | context} to get candidates for.
+   * @param options - Optional {@link Context.IContextMatchOptions | context match options} to use when matching candidates.
+   * @returns An array of {@link Resources.ResourceCandidate | candidates} that match the given context.
+   */
+  public getCandidatesForContext(
+    context: Context.IValidatedContextDecl,
+    options?: Context.IContextMatchOptions
+  ): ReadonlyArray<ResourceCandidate> {
+    return Array.from(this._candidates.values()).filter((candidate) =>
+      candidate.canMatchPartialContext(context, options)
+    );
+  }
+
+  /**
+   * Given a {@link ResourceJson.Json.IChildResourceCandidateDecl | child resource candidate declaration}, creates and adds a
+   * {@link Resources.ResourceCandidate | candidate} to the resource being built.
+   * @param candidate - The {@link ResourceJson.Json.IChildResourceCandidateDecl | IChildResourceCandidateDecl} to add to the
+   * resource being built.
+   * @returns `Success` with the added {@link Resources.ResourceCandidate | candidate} if successful,
+   * or `Failure` with an error message if not.
+   */
+  public addChildCandidate(
+    childDecl: ResourceJson.Json.IChildResourceCandidateDecl
+  ): DetailedResult<ResourceCandidate, ResourceBuilderResultDetail> {
+    return ResourceCandidate.create({
+      id: this.id,
+      resourceType: this._resourceType,
+      decl: childDecl,
+      conditionSets: this._conditionSets
+    })
+      .withDetail<ResourceBuilderResultDetail>('failure', 'success')
+      .onSuccess((candidate) => {
+        return this._candidates
+          .getOrAdd(candidate.conditions.toString(), candidate)
+          .onSuccess((added, detail) => {
+            if (detail === 'exists') {
+              if (!ResourceCandidate.equal(added, candidate)) {
+                return failWithDetail<ResourceCandidate, Collections.ResultMapResultDetail>(
+                  `${this.id}: conflicting candidates.`,
+                  'exists'
+                );
+              }
+            }
+            return succeedWithDetail(added, detail);
+          });
+      });
+  }
+
+  /**
+   * Given a {@link ResourceJson.Json.ILooseResourceCandidateDecl | resource candidate declaration}, creates and adds a
+   * {@link Resources.ResourceCandidate | candidate} to the resource being built.
+   * @param candidate - The {@link ResourceJson.Json.ILooseResourceCandidateDecl | IResourceCandidateDecl} to add to the
+   * resource being built.
+   * @returns `Success` with the added {@link Resources.ResourceCandidate | candidate} if successful,
+   * or `Failure` with an error message if not. Fails with error detail 'type-mismatch' if the candidate
+   * specifies a different resource type than previously added candidates, or with 'exists' if a candidate
+   * already exists with the same conditions but different values.  Succeeds with 'exists' and returns the
+   * existing candidate if the candidate to be added is identical to an existing candidate.
+   */
+  public addLooseCandidate(
+    decl: ResourceJson.Json.ILooseResourceCandidateDecl
+  ): DetailedResult<ResourceCandidate, ResourceBuilderResultDetail> {
+    /* c8 ignore next 6 - functional code path tested but coverage intermittently missed */
+    if (decl.id !== this.id) {
+      return failWithDetail<ResourceCandidate, ResourceBuilderResultDetail>(
+        `${this.id}: mismatched candidate id ${decl.id}.`,
+        'id-mismatch'
+      );
+    }
+
+    if (decl.resourceTypeName !== undefined) {
+      const rt = this.setResourceType(decl.resourceTypeName);
+      if (rt.isFailure()) {
+        return failWithDetail<ResourceCandidate, ResourceBuilderResultDetail>(rt.message, 'type-mismatch');
+      }
+    }
+
+    return this.addChildCandidate(decl);
+  }
+
+  /**
+   * Sets the resource type for the resource being built.  Fails if a resource type has already been set
+   * and it does not match the new resource type.
+   * @param resourceTypeName - The name of the resource type to set.
+   * @returns `Success` with the updated {@link Resources.ResourceBuilder | ResourceBuilder} object if successful,
+   * or `Failure` with an error message if not.
+   */
+  public setResourceType(resourceTypeName: string): Result<ResourceBuilder> {
+    if (this._resourceType?.key === resourceTypeName) {
+      return succeed(this);
+    } else if (this._resourceType !== undefined) {
+      return fail(
+        `${this.id}: conflicting resource types ${this._resourceType.key} !== ${resourceTypeName}.`
+      );
+    }
+    return this._resourceTypes.validating.get(resourceTypeName).onSuccess((resourceType) => {
+      this._resourceType = resourceType;
+      return succeedWithDetail(this, 'success');
+    });
+  }
+
+  /**
+   * Builds the {@link Resources.Resource | resource} object from this builder.
+   * @returns `Success` with the new {@link Resources.Resource | Resource} object if successful,
+   * or `Failure` with an error message if not. Fails if no candidates have been added
+   * or if the resource type is not defined.
+   */
+  public build(): Result<Resource> {
+    /* c8 ignore next 3 - functional code path tested but coverage intermittently missed */
+    if (this._candidates.size === 0) {
+      return fail(`${this.id}: no candidates supplied.`);
+    }
+
+    /* c8 ignore next 3 - functional code path tested but coverage intermittently missed */
+    if (this._resourceType === undefined) {
+      return fail(`${this.id}: no resource type supplied or inferred.`);
+    }
+
+    return Resource.create({
+      id: this.id,
+      resourceType: this._resourceType,
+      candidates: this.candidates,
+      decisions: this._decisions
+    });
+  }
+}