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

package/src/packlets/common/validate/regularExpressions.ts

@@ -0,0 +1,92 @@
+/*
+ * 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.
+ */
+
+/**
+ * @internal
+ */
+export const identifier: RegExp = /^[a-zA-Z_][a-zA-Z0-9_\-]*$/;
+
+/**
+ * @internal
+ */
+export const segmentedIdentifier: RegExp = /^[a-zA-Z_][a-zA-Z0-9_\-]*(\.[a-zA-Z_][a-zA-Z0-9_\-]*)*$/;
+
+/**
+ * @internal
+ */
+export const identifierList: RegExp = /^[a-zA-Z_][a-zA-Z0-9_\-]*(,[a-zA-Z_][a-zA-Z0-9_\-]*)*$/;
+
+/**
+ * The format of a {@link ConditionKey | condition key} is:
+ * <qualifierName>-[<value>][\@<priority>](<scoreAsDefault>) where operator is `matches`, or
+ * <qualifierName>-<operator>-[<value>][\@<priority>](<scoreAsDefault>)
+ * @internal
+ */
+export const conditionKey: RegExp =
+  /^[a-zA-Z_][a-zA-Z0-9_\-]*(-matches)?-\[.*\](?:@[0-9]{1,4})?(?:\([01](?:\.[0-9]+)?\))?$/;
+
+/**
+ * A {@link ConditionToken | condition token} is a comma-separated list of one or more
+ * condition specifiers, where a condition specifier has either the form
+ * `<qualifierName>=<value>` or `<value>`.
+ * @internal
+ */
+export const conditionToken: RegExp = /^[a-zA-Z_][a-zA-Z0-9_\-]*(?:=[a-zA-Z0-9_\-]+)?$/;
+
+/**
+ * A {@link ContextToken | context token} has the form `<qualifierName>=<value>` or `<value>`.
+ * Context tokens allow broader character set including commas for comma-separated values.
+ * @internal
+ */
+export const contextToken: RegExp = /^[a-zA-Z_][a-zA-Z0-9_\-]*(?:=[a-zA-Z0-9_\-,\s]+)?$/;
+
+/**
+ * @internal
+ */
+export const conditionSetHash: RegExp = /^[a-zA-Z0-9]{8}$/;
+
+/**
+ * @internal
+ */
+export const decisionKey: RegExp = /^[a-zA-Z0-9]{8}(?:\+[a-zA-Z0-9]{8})*(?:\|[a-zA-Z0-9]{8})?$/;
+
+/**
+ * A {@link QualifierDefaultValueToken | qualifier default value token} has the form
+ * `<qualifierName>=<value>` or `<qualifierName>=` (to remove default).
+ * Default values allow broader character set including commas for comma-separated values.
+ * @internal
+ */
+export const qualifierDefaultValueToken: RegExp = /^[a-zA-Z_][a-zA-Z0-9_\-]*=(?:[a-zA-Z0-9_\-,\s]*)?$/;
+
+/**
+ * A {@link QualifierDefaultValuesToken | qualifier default values token} is a
+ * pipe-separated list of one or more qualifier default value tokens.
+ * Uses "|" as separator to avoid conflicts with comma-separated values within defaults.
+ * @internal
+ */
+export const qualifierDefaultValuesToken: RegExp =
+  /^[a-zA-Z_][a-zA-Z0-9_\-]*=(?:[a-zA-Z0-9_\-,\s]*)?(?:\|[a-zA-Z_][a-zA-Z0-9_\-]*=(?:[a-zA-Z0-9_\-,\s]*)?)*$/;
+
+/**
+ * @internal
+ */
+export const territoryCode: RegExp = /^[a-zA-Z]{2}$/;

package/src/packlets/common/validate/resources.ts

@@ -0,0 +1,170 @@
+/*
+ * 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 { fail, succeed, Result } from '@fgv/ts-utils';
+import { ResourceId, ResourceIndex, ResourceName, ResourceTypeIndex, ResourceTypeName } from '../resources';
+import { identifier, segmentedIdentifier } from './regularExpressions';
+
+/**
+ * Checks if the given name is a valid resource name.
+ *
+ * @param name - The name to validate.
+ * @returns `true` if the name is a valid resource name, otherwise `false`.
+ * @public
+ */
+export function isValidResourceName(name: string): name is ResourceName {
+  return identifier.test(name);
+}
+
+/**
+ * Checks if the given ID is a valid resource ID.
+ *
+ * @param id - The ID to validate.
+ * @returns `true` if the ID is a valid resource ID, otherwise `false`.
+ * @public
+ */
+export function isValidResourceId(id: string): id is ResourceId {
+  return segmentedIdentifier.test(id);
+}
+
+/**
+ * Checks if the given index is a valid resource index.
+ *
+ * @param index - The index to validate.
+ * @returns `true` if the index is a valid resource index, otherwise `false`.
+ * @public
+ */
+export function isValidResourceIndex(index: number): index is ResourceIndex {
+  return index >= 0;
+}
+
+/**
+ * Checks if the given name is a valid resource type name.
+ *
+ * @param name - The name to validate.
+ * @returns `true` if the name is a valid resource type name, otherwise `false`.
+ * @public
+ */
+export function isValidResourceTypeName(name: string): name is ResourceTypeName {
+  return identifier.test(name);
+}
+
+/**
+ * Checks if the given index is a valid resource type index.
+ *
+ * @param index - The index to validate.
+ * @returns `true` if the index is a valid resource type index, otherwise `false`.
+ * @public
+ */
+export function isValidResourceTypeIndex(index: number): index is ResourceTypeIndex {
+  return index >= 0;
+}
+
+/**
+ * Converts a string to a {@link ResourceName | resource name}.
+ *
+ * @param id - The string to convert.
+ * @returns `Success` with the converted name if valid, or `Failure` with an error message
+ * if not.
+ * @public
+ */
+export function toResourceName(name: string): Result<ResourceName> {
+  /* c8 ignore next 3 - coverage having issues */
+  if (!isValidResourceName(name)) {
+    return fail(`${name}: not a valid resource name.`);
+  }
+  return succeed(name);
+}
+
+/**
+ * Converts a string to a {@link ResourceId | resource ID}.
+ *
+ * @param id - The string to convert.
+ * @returns `Success` with the converted ID if valid, or `Failure` with an error message
+ * if not.
+ * @public
+ */
+export function toResourceId(id: string): Result<ResourceId> {
+  if (!isValidResourceId(id)) {
+    return fail(`${id}: not a valid resource ID.`);
+  }
+  return succeed(id);
+}
+
+/**
+ * Converts an optional string to an optional {@link ResourceId | resource ID}.
+ *
+ * @param id - The string to convert.
+ * @returns `Success` with the converted ID if valid, or `Failure` with an error message
+ * if not.
+ * @public
+ */
+export function toOptionalResourceId(id?: string): Result<ResourceId | undefined> {
+  return id ? toResourceId(id) : succeed(undefined);
+}
+
+/**
+ * Converts a number to a {@link ResourceIndex | resource index}.
+ *
+ * @param index - The number to convert.
+ * @returns `Success` with the converted index if valid, or `Failure` with an error message
+ * if not.
+ * @public
+ */
+export function toResourceIndex(index: number): Result<ResourceIndex> {
+  if (!isValidResourceIndex(index)) {
+    return fail(`${index}: not a valid resource index.`);
+  }
+  return succeed(index);
+}
+
+/**
+ * Converts a string to a {@link ResourceTypeName | resource type name}.
+ *
+ * @param name - The string to convert.
+ * @returns `Success` with the converted name if valid, or `Failure` with an error message
+ * if not.
+ * @public
+ */
+export function toResourceTypeName(name: string): Result<ResourceTypeName> {
+  /* c8 ignore next 3 - coverage having issues */
+  if (!isValidResourceTypeName(name)) {
+    return fail(`${name}: not a valid resource type name.`);
+  }
+  return succeed(name);
+}
+
+/**
+ * Converts a number to a {@link ResourceTypeIndex | resource type index}.
+ *
+ * @param index - The number to convert.
+ * @returns `Success` with the converted index if valid, or `Failure` with an error message
+ * if not.
+ * @public
+ */
+export function toResourceTypeIndex(index: number): Result<ResourceTypeIndex> {
+  /* c8 ignore next 3 - coverage having issues */
+  if (!isValidResourceTypeIndex(index)) {
+    return fail(`${index}: not a valid resource type index.`);
+  }
+  return succeed(index);
+}

package/src/packlets/conditions/condition.ts

@@ -0,0 +1,351 @@
+/*
+ * 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 { captureResult, Collections, Result, fail } from '@fgv/ts-utils';
+import {
+  Convert as CommonConvert,
+  ConditionIndex,
+  ConditionKey,
+  ConditionOperator,
+  ConditionPriority,
+  ConditionToken,
+  NoMatch,
+  QualifierConditionValue,
+  QualifierMatchScore,
+  Validate
+} from '../common';
+import { Qualifier } from '../qualifiers';
+import { IValidatedConditionDecl } from './conditionDecls';
+import * as ResourceJson from '../resource-json';
+import * as Context from '../context';
+
+// eslint-disable-next-line @rushstack/typedef-var
+const scoreFormatter = new Intl.NumberFormat('en-US', { minimumFractionDigits: 0, maximumFractionDigits: 3 });
+
+/**
+ * Represents a single condition applied to some resource instance.
+ * @public
+ */
+export class Condition implements IValidatedConditionDecl {
+  /**
+   * The {@link Qualifiers.Qualifier | qualifier} used in this condition.
+   */
+  public readonly qualifier: Qualifier;
+
+  /**
+   * The value to be matched in this condition.
+   */
+  public readonly value: QualifierConditionValue;
+
+  /**
+   * The {@link ConditionOperator | operator} used when matching context value to condition value.
+   */
+  public readonly operator: ConditionOperator;
+
+  /**
+   * The {@link ConditionPriority | relative priority} of this condition.
+   */
+  public readonly priority: ConditionPriority;
+
+  /**
+   * The {@link QualifierMatchScore | score} to be used when this condition is the default.
+   */
+  public readonly scoreAsDefault?: QualifierMatchScore;
+
+  protected _collectible: Collections.Collectible<ConditionKey, ConditionIndex>;
+
+  /**
+   * Constructs a new {@link Conditions.Condition | Condition} object.
+   * @param qualifier - The {@link Qualifiers.Qualifier | qualifier} used in this condition.
+   * @param value - The value to be matched in this condition.
+   * @param operator - The {@link ConditionOperator | operator} used when matching context value to condition value.
+   * @param priority - The {@link ConditionPriority | relative priority} of this condition.
+   * @param scoreAsDefault - The {@link QualifierMatchScore | score} to be used when this condition is the default.
+   * @param index - The index of this condition.
+   * @public
+   */
+  protected constructor({
+    qualifier,
+    value,
+    operator,
+    priority,
+    scoreAsDefault,
+    index
+  }: IValidatedConditionDecl) {
+    if (scoreAsDefault === undefined && qualifier.defaultValue !== undefined) {
+      const defaultMatch = qualifier.type.matches(value, qualifier.defaultValue, 'matches');
+      if (defaultMatch !== NoMatch) {
+        scoreAsDefault = defaultMatch;
+      }
+    }
+    this.qualifier = qualifier;
+    this.operator = operator;
+    this.value = qualifier.validateCondition(value, operator).orThrow();
+    this.priority = priority;
+    this.scoreAsDefault = scoreAsDefault;
+    this._collectible = new Collections.Collectible({
+      key: this.toKey(),
+      index,
+      indexConverter: CommonConvert.conditionIndex
+    });
+  }
+
+  public get key(): ConditionKey {
+    return this._collectible.key;
+  }
+
+  public get index(): ConditionIndex | undefined {
+    return this._collectible.index;
+  }
+
+  public setIndex(index: ConditionIndex): Result<ConditionIndex> {
+    return this._collectible.setIndex(index);
+  }
+
+  /**
+   * Creates a new {@link Conditions.Condition | Condition} object from the supplied
+   * {@link Conditions.IValidatedConditionDecl | validated condition declaration}.
+   * @param decl - The {@link Conditions.IValidatedConditionDecl | validated condition declaration}
+   * describing the condition to create.
+   * @returns `Success` with the new {@link Conditions.Condition | Condition} if successful,
+   * `Failure` otherwise.
+   * @public
+   */
+  public static create(decl: IValidatedConditionDecl): Result<Condition> {
+    return captureResult(() => new Condition(decl));
+  }
+
+  /**
+   * Determines if this condition matches the supplied {@link Context.IValidatedContextDecl | validated context}.
+   * @param context - The {@link Context.IValidatedContextDecl | context} to match against.
+   * @param options - The {@link Context.IContextMatchOptions | options} to use when matching the context.
+   * @returns A {@link QualifierMatchScore | match score} indicating match quality if the condition is present
+   * in the context to be matched, `undefined` otherwise.
+   * @remarks
+   * If {@link Context.IContextMatchOptions.partialContextMatch | `options.partialContextMatch``} is `true`, then
+   * the method will return `undefined` if the corresponding qualifier is not present in the context.
+   */
+  public getContextMatch(
+    context: Context.IValidatedContextDecl,
+    options?: Context.IContextMatchOptions
+  ): QualifierMatchScore | undefined {
+    options = options ?? {};
+    if (this.qualifier.name in context) {
+      const contextValue = context[this.qualifier.name];
+      const match = this.qualifier.type.matches(this.value, contextValue, this.operator);
+      if (match === NoMatch && options.acceptDefaultScore === true && this.scoreAsDefault !== undefined) {
+        return this.scoreAsDefault;
+      }
+      return match;
+    }
+    return options.partialContextMatch === true ? undefined : NoMatch;
+  }
+
+  /**
+   * Determines if this condition can match the supplied context, even if the context is partial.
+   *
+   * Returns true if:
+   * - The qualifier specified in the condition is not present in the context
+   * - The qualifier is present and matches the condition
+   *
+   * Returns false if:
+   * - The qualifier is present in the context and does not match the condition
+   *
+   * @param context - The context to match against.
+   * @param options - Options to use when matching the context.
+   * @returns `true` if the condition can match the (possibly partial) context, `false` otherwise.
+   * @public
+   */
+  public canMatchPartialContext(
+    context: Context.IValidatedContextDecl,
+    options?: Context.IContextMatchOptions
+  ): boolean {
+    /* c8 ignore next 1 - defense in depth */
+    const scoreAsDefault = this.scoreAsDefault ?? NoMatch;
+    if (!(this.qualifier.name in context) || scoreAsDefault > NoMatch) {
+      return true;
+    }
+    return this.qualifier.type.isPotentialMatch(this.value, context[this.qualifier.name]);
+  }
+
+  /**
+   * Compares two conditions for sorting purposes.
+   * @param c1 - The first {@link Conditions.Condition | condition} to compare.
+   * @param c2 - The second {@link Conditions.Condition | condition} to compare.
+   * @returns A negative number if c1 should come before c2, a positive number
+   * if c2 should come before c1, or zero if they are equivalent.
+   * @public
+   */
+  public static compare(c1: Condition, c2: Condition): number {
+    let diff = c1.priority - c2.priority;
+    diff = diff === 0 ? (c1.scoreAsDefault ?? 0) - (c2.scoreAsDefault ?? 0) : diff;
+    diff = diff === 0 ? c1.qualifier.name.localeCompare(c2.qualifier.name) : diff;
+    diff = diff === 0 ? c1.value.localeCompare(c2.value) : diff;
+    return diff;
+  }
+
+  /**
+   * Gets a {@link ConditionToken | condition token} for this condition, if possible.
+   * It is not possible to get a token for a condition with an operator other than `matches`,
+   * with other-than-default priority, or with a name or value that contains other than alphanumeric
+   * characters, underscore or non-leading hyphen.
+   * @param terse - if `true` and if the qualifier token is optional, the token will be omitted
+   * from the generated {@link ConditionToken | condition token}.
+   * @returns
+   */
+  public toToken(terse?: boolean): Result<ConditionToken> {
+    /* c8 ignore next 3 - defense in depth very difficult to induce */
+    if (this.operator !== 'matches') {
+      return fail(`${this.operator}: cannot create condition token for operator other than 'matches'`);
+    }
+    if (this.priority !== this.qualifier.defaultPriority) {
+      return fail(`${this.priority}: cannot create condition token for non-default priority`);
+    }
+    if (terse && this.qualifier.tokenIsOptional) {
+      return Validate.toConditionToken(this.value);
+    }
+    /* c8 ignore next 1 - coverage having a bad day */
+    const name = this.qualifier.token ?? this.qualifier.name;
+    return Validate.toConditionToken(`${name}=${this.value}`);
+  }
+
+  /**
+   * Gets the {@link ConditionKey | key} for this condition.
+   * @returns -
+   */
+  public toKey(): ConditionKey {
+    return Condition.getKeyForDecl(this).orThrow();
+  }
+
+  /**
+   * Get a human-readable string representation of the condition.
+   * @returns A string representation of the condition.
+   * @public
+   */
+  public toString(): string {
+    return this.toKey();
+  }
+
+  /**
+   * Gets the {@link ResourceJson.Json.IChildConditionDecl | child condition declaration} for this condition.
+   * @param options - The {@link ResourceJson.Helpers.IDeclarationOptions | options} to use when creating the child
+   * condition declaration.
+   * @returns The {@link ResourceJson.Json.IChildConditionDecl | child condition declaration} for this condition.
+   * @public
+   */
+  public toChildConditionDecl(
+    options?: ResourceJson.Helpers.IDeclarationOptions
+  ): ResourceJson.Json.IChildConditionDecl {
+    const showDefaults = options?.showDefaults === true;
+    return {
+      value: this.value,
+      /* c8 ignore next 1 - not really possible to reproduce right now */
+      ...(showDefaults || this.operator !== 'matches' ? { operator: this.operator } : {}),
+      ...(showDefaults || this.priority !== this.qualifier.defaultPriority
+        ? { priority: this.priority }
+        : {}),
+      ...(this.scoreAsDefault ? { scoreAsDefault: this.scoreAsDefault } : {})
+    };
+  }
+
+  /**
+   * Gets the value for this condition, or the {@link ResourceJson.Json.IChildConditionDecl | child condition declaration}
+   * if the condition has non-default operator, priority or a score as default.
+   * @param options - The {@link ResourceJson.Helpers.IDeclarationOptions | options} to use when creating the child
+   * condition declaration.
+   * @returns A string value for this condition, or the {@link ResourceJson.Json.IChildConditionDecl | child condition declaration}
+   * if the condition has non-default operator, priority or a score as default.
+   */
+  public toValueOrChildConditionDecl(
+    options?: ResourceJson.Helpers.IDeclarationOptions
+  ): string | ResourceJson.Json.IChildConditionDecl {
+    if (
+      options?.showDefaults !== true &&
+      this.operator === 'matches' &&
+      this.priority === this.qualifier.defaultPriority &&
+      this.scoreAsDefault === undefined
+    ) {
+      return this.value;
+    }
+    /* c8 ignore next 2 - unreachable: matches is the only real operator in practice */
+    return this.toChildConditionDecl(options);
+  }
+
+  /**
+   * Gets the {@link ResourceJson.Json.ILooseConditionDecl | loose condition declaration} for this condition.
+   * @param options - The {@link ResourceJson.Helpers.IDeclarationOptions | options} to use when creating the loose
+   * condition declaration.
+   * @returns The {@link ResourceJson.Json.ILooseConditionDecl | loose condition declaration} for this condition.
+   * @public
+   */
+  public toLooseConditionDecl(
+    options?: ResourceJson.Helpers.IDeclarationOptions
+  ): ResourceJson.Json.ILooseConditionDecl {
+    const showDefaults = options?.showDefaults === true;
+    return {
+      qualifierName: this.qualifier.name,
+      value: this.value,
+      /* c8 ignore next 1 - not really possible to reproduce right now */
+      ...(showDefaults || this.operator !== 'matches' ? { operator: this.operator } : {}),
+      ...(showDefaults || this.priority !== this.qualifier.defaultPriority
+        ? { priority: this.priority }
+        : {}),
+      ...(this.scoreAsDefault ? { scoreAsDefault: this.scoreAsDefault } : {})
+    };
+  }
+
+  /**
+   * Converts this condition to a compiled condition representation.
+   * @param options - Optional compilation options controlling the output format.
+   * @returns A compiled condition object that can be used for serialization or runtime processing.
+   * @public
+   */
+  public toCompiled(
+    options?: ResourceJson.Compiled.ICompiledResourceOptions
+  ): ResourceJson.Compiled.ICompiledCondition {
+    /* c8 ignore next 1 - defense in depth */
+    const operator = this.operator === 'matches' ? undefined : this.operator;
+    return {
+      qualifierIndex: this.qualifier.index!,
+      operator,
+      value: this.value,
+      priority: this.priority,
+      scoreAsDefault: this.scoreAsDefault,
+      ...(options?.includeMetadata === true ? { metadata: { key: this.key } } : {})
+    };
+  }
+
+  /**
+   * Gets the {@link ConditionKey | condition key} for a supplied {@link Conditions.IValidatedConditionDecl | condition declaration}.
+   * @param decl - The {@link Conditions.IValidatedConditionDecl | condition declaration} for which to get the key.
+   * @returns `Success` with the condition key if successful, `Failure` otherwise.
+   * @public
+   */
+  public static getKeyForDecl(decl: IValidatedConditionDecl): Result<ConditionKey> {
+    const scoreAsDefault = decl.scoreAsDefault ? `(${scoreFormatter.format(decl.scoreAsDefault)})` : '';
+    const key =
+      decl.operator === 'matches'
+        ? `${decl.qualifier.name}-[${decl.value}]@${decl.priority}${scoreAsDefault}`
+        : `${decl.qualifier.name}-${decl.operator}-[${decl.value}]@${decl.priority}${scoreAsDefault}`;
+    return Validate.toConditionKey(key);
+  }
+}