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

package/src/packlets/resources/resourceCandidate.ts

@@ -0,0 +1,333 @@
+/*
+ * 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 { JsonObject } from '@fgv/ts-json-base';
+import {
+  CandidateCompleteness,
+  PerfectMatch,
+  QualifierName,
+  ResourceId,
+  ResourceValueMergeMethod,
+  Validate
+} from '../common';
+import { Condition, ConditionSet, ConditionSetCollector } from '../conditions';
+import * as ResourceJson from '../resource-json';
+import { ResourceType } from '../resource-types';
+import { captureResult, mapResults, Hash, MessageAggregator, Result, fail, succeed } from '@fgv/ts-utils';
+import * as Context from '../context';
+import { IResourceCandidate } from '../runtime';
+
+/**
+ * Parameters to create a {@link Resources.ResourceCandidate | ResourceCandidate}.
+ * @public
+ */
+export interface IResourceCandidateCreateParams {
+  id: string;
+  decl: ResourceJson.Json.IChildResourceCandidateDecl;
+  resourceType?: ResourceType;
+  parentConditions?: ReadonlyArray<Condition>;
+  conditionSets: ConditionSetCollector;
+}
+
+/**
+ * Options for creating a {@link Resources.ResourceCandidate | ResourceCandidate} declaration.
+ * @remarks
+ * This interface extends the {@link ResourceJson.Helpers.IDeclarationOptions | declaration options}
+ * interface to include a `reduceQualifiers` option.
+ * @public
+ */
+export interface ICandidateDeclOptions extends ResourceJson.Helpers.IDeclarationOptions {
+  /**
+   * If provided, reduces the qualifiers of the candidate by removing qualifiers that are made
+   * irrelevant by the filterForContext.
+   */
+  qualifiersToReduce?: ReadonlySet<QualifierName>;
+}
+
+/**
+ * A {@link Resources.ResourceCandidate | resource candidate} represents a single possible
+ * instance value for some resource, with the conditions under which it applies
+ * and instructions on how to merge it with other instances.
+ * @public
+ */
+export class ResourceCandidate implements IResourceCandidate {
+  /**
+   * The unique identifier of the resource for which this candidate
+   * is a possible instance.
+   */
+  public readonly id: ResourceId;
+
+  /**
+   * The JSON representation of the instance data to be applied.
+   */
+  public readonly json: JsonObject;
+
+  /**
+   * The conditions under which this candidate applies.
+   */
+  public readonly conditions: ConditionSet;
+
+  /**
+   * True if this candidate is a partial instance.
+   */
+  public readonly isPartial: boolean;
+
+  /**
+   * The method to use when merging this candidate with other instances.
+   */
+  public readonly mergeMethod: ResourceValueMergeMethod;
+
+  /**
+   * The {@link ResourceTypes.ResourceType | resource type} for the resource to which
+   * this candidate belongs.
+   */
+  public readonly resourceType: ResourceType | undefined;
+
+  /**
+   * The completeness of the candidate value.
+   */
+  public get completeness(): CandidateCompleteness {
+    return this.isPartial ? 'partial' : 'full';
+  }
+
+  /**
+   * Constructor for a {@link Resources.ResourceCandidate | ResourceCandidate} object.
+   * @param params - Parameters to create a new {@link Resources.ResourceCandidate | ResourceCandidate}.
+   * @public
+   */
+  protected constructor(params: IResourceCandidateCreateParams) {
+    this.id = Validate.toResourceId(params.id).orThrow();
+    this.json = params.decl.json;
+    this.conditions = ResourceCandidate._mergeConditions(
+      params.conditionSets,
+      params.decl.conditions,
+      params.parentConditions
+    ).orThrow();
+    this.isPartial = params.decl.isPartial ?? false;
+    this.mergeMethod = params.decl.mergeMethod ?? 'augment';
+    this.resourceType = params.resourceType;
+    if (this.resourceType) {
+      this.resourceType.validateDeclaration(this).orThrow();
+    }
+  }
+
+  /**
+   * Creates a new {@link Resources.ResourceCandidate | ResourceCandidate} object.
+   * @param params - Parameters to create a new {@link Resources.ResourceCandidate | ResourceCandidate}.
+   * @returns `Success` with the new {@link Resources.ResourceCandidate | ResourceCandidate} object if successful,
+   * or `Failure` with an error message if not.
+   * @public
+   */
+  public static create(params: IResourceCandidateCreateParams): Result<ResourceCandidate> {
+    return captureResult(() => new ResourceCandidate(params));
+  }
+
+  /**
+   * Determines if this candidate can match the supplied context (possibly partial).
+   * @param context - The context to match.
+   * @param options - Options to use when matching.
+   * @returns `true` if the candidate can match the context, `false` otherwise.
+   */
+  public canMatchPartialContext(
+    context: Context.IValidatedContextDecl,
+    options?: Context.IContextMatchOptions
+  ): boolean {
+    return this.conditions.canMatchPartialContext(context, options);
+  }
+
+  /**
+   * Gets the {@link ResourceJson.Json.IChildResourceCandidateDecl | child resource candidate declaration}
+   * for this candidate.
+   * @param options - {@link ResourceJson.Helpers.IDeclarationOptions | options} to use when creating the declaration.
+   * @returns The {@link ResourceJson.Json.IChildResourceCandidateDecl | child resource candidate declaration}.
+   */
+  public toChildResourceCandidateDecl(
+    options?: ICandidateDeclOptions
+  ): ResourceJson.Json.IChildResourceCandidateDecl {
+    const showDefaults = options?.showDefaults === true;
+    return {
+      json: this.json as JsonObject,
+      conditions: this.conditions.toConditionSetRecordDecl(options),
+      ...(showDefaults || this.isPartial ? { isPartial: this.isPartial } : {}),
+      ...(showDefaults || this.mergeMethod !== 'augment' ? { mergeMethod: this.mergeMethod } : {})
+    };
+  }
+
+  /**
+   * Gets the {@link ResourceJson.Json.ILooseResourceCandidateDecl | loose resource candidate declaration}
+   * for this candidate.
+   * @param options - {@link ResourceJson.Helpers.IDeclarationOptions | options} to use when creating the declaration.
+   * @returns The {@link ResourceJson.Json.ILooseResourceCandidateDecl | loose resource candidate declaration}.
+   */
+  public toLooseResourceCandidateDecl(
+    options?: ICandidateDeclOptions
+  ): ResourceJson.Json.ILooseResourceCandidateDecl {
+    const showDefaults = options?.showDefaults === true;
+    const resourceTypeName = this.resourceType?.key;
+    return {
+      id: this.id.toString(),
+      json: this.json as JsonObject,
+      conditions: this.conditions.toConditionSetRecordDecl(options),
+      ...(showDefaults || this.isPartial ? { isPartial: this.isPartial } : {}),
+      ...(showDefaults || this.mergeMethod !== 'augment' ? { mergeMethod: this.mergeMethod } : {}),
+      ...(resourceTypeName ? { resourceTypeName } : {})
+    };
+  }
+
+  /**
+   * Extracts the {@link ResourceTypes.ResourceType | resource type} from a list of {@link Resources.ResourceCandidate | resource candidates},
+   * if present.
+   * @param candidates - The list of candidates from which to extract the resource type.
+   * @returns `Success` with the resource type if successful, `Success` with `undefined` if none of the candidates
+   * specify a resource tap, and `Failure` with an error message if clients specify conflicting resource types.
+   * @public
+   */
+  public static validateResourceTypes(
+    candidates: ReadonlyArray<ResourceCandidate>,
+    expectedType?: ResourceType
+  ): Result<ResourceType | undefined> {
+    const errors = new MessageAggregator();
+    let selectedType: ResourceType | undefined = expectedType;
+    for (const candidate of candidates) {
+      if (selectedType === undefined) {
+        /* c8 ignore next 1 - functional code path tested but coverage intermittently missed */
+        selectedType = candidate.resourceType;
+      } else if (candidate.resourceType && selectedType !== candidate.resourceType) {
+        /* c8 ignore next 4 - functional code path tested but coverage intermittently missed */
+        errors.addMessage(
+          `${candidate.id}: resource type mismatch (${selectedType.key} != ${candidate.resourceType.key})`
+        );
+      }
+    }
+    return errors.returnOrReport(succeed(selectedType));
+  }
+
+  /**
+   * Compares two {@link Resources.ResourceCandidate | ResourceCandidates} for sorting purposes.
+   * @param rc1 - The first candidate to compare.
+   * @param rc2 - The second candidate to compare.
+   * @returns A negative number if `rc1` should come before `rc2`, a positive number if `rc2` should come before `rc1`,
+   * or zero if they are equivalent.
+   * @public
+   */
+  public static compare(rc1: ResourceCandidate, rc2: ResourceCandidate): number {
+    return ConditionSet.compare(rc1.conditions, rc2.conditions);
+  }
+
+  /**
+   * Compares two {@link Resources.ResourceCandidate | ResourceCandidates} for equality.
+   * @param rc1 - The first candidate to compare.
+   * @param rc2 - The second candidate to compare.
+   * @returns `true` if the candidates are equal, `false` otherwise.
+   * @public
+   */
+  public static equal(rc1: ResourceCandidate, rc2: ResourceCandidate): boolean {
+    /* c8 ignore next 3 - functional code path tested but coverage intermittently missed */
+    if (rc1 === rc2) {
+      return true;
+    }
+    let equal =
+      rc1.id === rc2.id &&
+      rc1.isPartial === rc2.isPartial &&
+      rc1.mergeMethod === rc2.mergeMethod &&
+      ConditionSet.compare(rc1.conditions, rc2.conditions) === 0;
+    if (equal) {
+      const normalizer = new 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;
+    }
+    return equal;
+  }
+
+  /**
+   * Validates declared conditions and merges them with parent conditions.
+   * @param conditionSets - The {@link Conditions.ConditionSetCollector | condition set collector}
+   * to use for this candidate.
+   * @param declared - The declared conditions for the candidate.
+   * @param parent - The parent conditions to merge with the declared conditions.
+   * @returns `Success` with the merged conditions if successful, `Failure` otherwise.
+   * @internal
+   */
+  private static _mergeConditions(
+    conditionSets: ConditionSetCollector,
+    declared: ResourceJson.Json.ConditionSetDecl | undefined,
+    parent: ReadonlyArray<Condition> | undefined
+  ): Result<ConditionSet> {
+    /* c8 ignore next 2 - code coverage is flaky */
+    declared = declared ?? {};
+    parent = parent ?? [];
+
+    const { value: conditionDecls, message } = ResourceJson.Convert.conditionSetDecl.convert(declared);
+    /* c8 ignore next 3 - functional code path tested but coverage intermittently missed */
+    if (message !== undefined) {
+      return fail(message);
+    }
+
+    return mapResults(
+      // get or add all declared conditions from our condition collector
+      conditionDecls.map((decl) => conditionSets.conditions.validating.getOrAdd(decl))
+    ).onSuccess((declaredConditions) => {
+      // make sure our parent conditions all come from our condition collector too
+      return mapResults(parent.map((c) => conditionSets.conditions.getOrAdd(c))).onSuccess(
+        (parentConditions) => {
+          const conditions = [...parentConditions, ...declaredConditions];
+          return conditionSets.validating.getOrAdd(conditions);
+        }
+      );
+    });
+  }
+
+  /**
+   * Finds the qualifiers that are made irrelevant by the supplied filterForContext.
+   * @param candidates - The candidates to find the reducible qualifiers for.
+   * @param filterForContext - The filter for context to use.
+   * @returns The qualifiers that are made irrelevant by the filterForContext.
+   * @remarks
+   * For any given set of candidates, qualifiers that match every candidate perfectly
+   * are irrelevant to the filtered content and can be removed.  Qualifiers that do not
+   * match, that are not in the filterForContext, or which partially match at least one
+   * candidate remain relevant and must not be removed.
+   * @public
+   */
+  public static findReducibleQualifiers(
+    candidates: ReadonlyArray<ResourceCandidate>,
+    filterForContext: Context.IValidatedContextDecl
+  ): ReadonlySet<QualifierName> | undefined {
+    const qualifiersToReduce = new Set<QualifierName>(Object.keys(filterForContext) as QualifierName[]);
+    for (const candidate of candidates) {
+      for (const condition of candidate.conditions.conditions) {
+        if (qualifiersToReduce.has(condition.qualifier.name)) {
+          const match = condition.qualifier.type.matches(
+            condition.value,
+            filterForContext[condition.qualifier.name],
+            'matches'
+          );
+          if (match !== PerfectMatch) {
+            qualifiersToReduce.delete(condition.qualifier.name);
+          }
+        }
+      }
+    }
+    return qualifiersToReduce.size > 0 ? qualifiersToReduce : undefined;
+  }
+}