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

package/src/packlets/qualifier-types/helpers.ts

@@ -0,0 +1,94 @@
+/*
+ * 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, Result } from '@fgv/ts-utils';
+import * as Config from './config';
+import { QualifierType } from './qualifierType';
+import { LanguageQualifierType } from './languageQualifierType';
+import { TerritoryQualifierType } from './territoryQualifierType';
+import { LiteralQualifierType } from './literalQualifierType';
+import { JsonObject } from '@fgv/ts-json-base';
+
+/**
+ * Creates a {@link QualifierTypes.QualifierType | QualifierType} from a configuration object.
+ * This factory function determines the appropriate qualifier type based on the systemType
+ * and delegates to the appropriate type-specific createFromConfig method.
+ * @param typeConfig - The {@link QualifierTypes.Config.IQualifierTypeConfig | configuration object}
+ * containing the name, systemType, and optional type-specific configuration.
+ * @returns `Success` with the new {@link QualifierTypes.QualifierType | QualifierType}
+ * if successful, `Failure` with an error message otherwise.
+ * @public
+ */
+export function createQualifierTypeFromConfig(
+  typeConfig: Config.IQualifierTypeConfig<JsonObject>
+): Result<QualifierType> {
+  /* c8 ignore next 1 - defense in depth */
+  const childConfig = typeConfig.configuration ?? {};
+  switch (typeConfig.systemType) {
+    case 'language':
+      return Config.Convert.languageQualifierTypeConfig
+        .convert(childConfig)
+        .onSuccess((configuration) =>
+          LanguageQualifierType.createFromConfig({ ...typeConfig, configuration })
+        );
+    case 'territory':
+      return Config.Convert.territoryQualifierTypeConfig
+        .convert(childConfig)
+        .onSuccess((configuration) =>
+          TerritoryQualifierType.createFromConfig({ ...typeConfig, configuration })
+        );
+    case 'literal':
+      return Config.Convert.literalQualifierTypeConfig
+        .convert(childConfig)
+        .onSuccess((configuration) =>
+          LiteralQualifierType.createFromConfig({ ...typeConfig, configuration })
+        );
+    default:
+      return fail(`Unknown qualifier type: ${typeConfig.systemType}`);
+  }
+}
+
+/**
+ * Creates a {@link QualifierTypes.QualifierType | QualifierType} from a system configuration object.
+ * This factory function determines the appropriate qualifier type based on the systemType
+ * and delegates to the appropriate type-specific createFromConfig method.
+ * @param typeConfig - The {@link QualifierTypes.Config.ISystemQualifierTypeConfig | configuration object}
+ * containing the name, systemType, and optional type-specific configuration.
+ * @returns `Success` with the new {@link QualifierTypes.QualifierType | QualifierType}
+ * if successful, `Failure` with an error message otherwise.
+ * @public
+ */
+export function createQualifierTypeFromSystemConfig(
+  typeConfig: Config.ISystemQualifierTypeConfig
+): Result<QualifierType> {
+  const { systemType } = typeConfig;
+  switch (systemType) {
+    case 'language':
+      return LanguageQualifierType.createFromConfig(typeConfig);
+    case 'territory':
+      return TerritoryQualifierType.createFromConfig(typeConfig);
+    case 'literal':
+      return LiteralQualifierType.createFromConfig(typeConfig);
+    default:
+      return fail(`${systemType}: Unknown system qualifier type.`);
+  }
+}

package/src/packlets/qualifier-types/index.ts

@@ -0,0 +1,34 @@
+/*
+ * 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 * as Config from './config';
+import * as Convert from './convert';
+
+export * from './qualifierType';
+export * from './languageQualifierType';
+export * from './literalQualifierType';
+export * from './literalValueHierarchy';
+export * from './territoryQualifierType';
+export * from './qualifierTypeCollector';
+export * from './helpers';
+
+export { Config, Convert };

package/src/packlets/qualifier-types/languageQualifierType.ts

@@ -0,0 +1,143 @@
+/*
+ * 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 { Result, captureResult, succeed } from '@fgv/ts-utils';
+import { Bcp47 } from '@fgv/ts-bcp47';
+import {
+  ConditionOperator,
+  Convert,
+  NoMatch,
+  QualifierConditionValue,
+  QualifierContextValue,
+  QualifierMatchScore,
+  Validate
+} from '../common';
+import { IQualifierTypeCreateParams, QualifierType } from './qualifierType';
+import * as Config from './config';
+import { sanitizeJsonObject } from '@fgv/ts-json-base';
+
+/**
+ * Interface defining the parameters that can be used to create a new
+ * {@link QualifierTypes.LanguageQualifierType | LanguageQualifierType}.
+ * @public
+ */
+export interface ILanguageQualifierTypeCreateParams extends Partial<IQualifierTypeCreateParams> {
+  /**
+   * Optional name for the qualifier type. Defaults to 'language'.
+   */
+  name?: string;
+
+  /**
+   * Optional flag indicating whether the context can be a list of values.
+   * Defaults to `true`.
+   */
+  allowContextList?: boolean;
+}
+
+/**
+ * {@link QualifierTypes.QualifierType | Qualifier type} which matches BCP-47 language tags
+ * applying {@link https://github.com/ErikFortune/fgv/tree/main/libraries/ts-bcp47#tag-matching | similarity matching}.
+ * Accepts a list of language tags in the context by default.
+ * @public
+ */
+export class LanguageQualifierType extends QualifierType {
+  /**
+   * Creates a new instance of a {@link QualifierTypes.LanguageQualifierType | language qualifier type}.
+   * @param name - Optional name for the qualifier type. Defaults to 'language'.
+   * @param allowContextList - Optional flag indicating whether the context can be a
+   * list of values. Defaults to `true`.
+   * @public
+   */
+  protected constructor({ name, allowContextList, index }: ILanguageQualifierTypeCreateParams) {
+    allowContextList = allowContextList !== false;
+    /* c8 ignore next 2 - coverage intermittently drops these two lines even though they're tested */
+    name = name ?? 'language';
+    const validated = index ? { index: Convert.qualifierTypeIndex.convert(index).orThrow() } : {};
+
+    super({
+      name,
+      allowContextList,
+      ...validated
+    });
+  }
+
+  /**
+   * Creates a new instance of a {@link QualifierTypes.LanguageQualifierType | language qualifier type}.
+   * @param params - Optional {@link QualifierTypes.ILanguageQualifierTypeCreateParams | parameters}
+   * to use when creating the new instance.
+   * @returns `Success` with the new {@link QualifierTypes.LanguageQualifierType | language qualifier type}
+   * if successful, `Failure` otherwise.
+   */
+  public static create(params?: ILanguageQualifierTypeCreateParams): Result<LanguageQualifierType> {
+    /* c8 ignore next 1 - coverage seems to intermittently miss the branch even though it's tested */
+    params = params ?? {};
+    return captureResult(() => new LanguageQualifierType(params));
+  }
+
+  /**
+   * Creates a new {@link QualifierTypes.LanguageQualifierType | LanguageQualifierType} from a configuration object.
+   * @param config - The {@link QualifierTypes.Config.IQualifierTypeConfig | configuration object} containing
+   * the name, systemType, and optional language-specific configuration.
+   * @returns `Success` with the new {@link QualifierTypes.LanguageQualifierType | LanguageQualifierType}
+   * if successful, `Failure` with an error message otherwise.
+   * @public
+   */
+  public static createFromConfig(
+    config: Config.IQualifierTypeConfig<Config.ILanguageQualifierTypeConfig>
+  ): Result<LanguageQualifierType> {
+    return sanitizeJsonObject<ILanguageQualifierTypeCreateParams>({
+      name: config.name,
+      allowContextList: config.configuration?.allowContextList === true
+    }).onSuccess(LanguageQualifierType.create);
+  }
+
+  /**
+   * {@inheritdoc QualifierTypes.IQualifierType.isValidConditionValue}
+   */
+  public isValidConditionValue(value: string): value is QualifierConditionValue {
+    return Bcp47.tag(value)
+      .onSuccess((tag) => succeed(tag.isValid))
+      .orDefault(false);
+  }
+
+  /**
+   * Matches a single language condition against a single language context value using
+   * {@link https://github.com/ErikFortune/fgv/tree/main/libraries/ts-bcp47#tag-matching | similarity matching}.
+   * @param condition - The language condition value to match.
+   * @param context - The language context value to match against.
+   * @param operator - The operator to use for the match. Must be 'matches'.
+   * @returns The match score, or `noMatch` if the match fails.
+   */
+  protected _matchOne(
+    condition: QualifierConditionValue,
+    context: QualifierContextValue,
+    operator: ConditionOperator
+  ): QualifierMatchScore {
+    if (operator === 'matches') {
+      const similarity = Bcp47.similarity(condition, context).orDefault(Bcp47.tagSimilarity.none);
+      if (similarity > 0.0 && Validate.isValidQualifierMatchScore(similarity)) {
+        return similarity;
+      }
+    }
+    return NoMatch;
+  }
+}

package/src/packlets/qualifier-types/literalQualifierType.ts

@@ -0,0 +1,244 @@
+/*
+ * 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, mapResults, Result, fail, succeed } from '@fgv/ts-utils';
+import {
+  ConditionOperator,
+  Convert,
+  NoMatch,
+  PerfectMatch,
+  QualifierConditionValue,
+  QualifierContextValue,
+  QualifierMatchScore,
+  Validate
+} from '../common';
+import { QualifierType } from './qualifierType';
+import { LiteralValueHierarchy, LiteralValueHierarchyDecl } from './literalValueHierarchy';
+import * as Config from './config';
+import { sanitizeJsonObject } from '@fgv/ts-json-base';
+
+/**
+ * Interface defining the parameters that can be used to create a new
+ * {@link QualifierTypes.LiteralQualifierType | LiteralQualifierType}.
+ * @public
+ */
+export interface ILiteralQualifierTypeCreateParams {
+  /**
+   * Optional name for the qualifier type. Defaults to 'literal'.
+   */
+  name?: string;
+
+  /**
+   * Optional flag indicating whether the context can be a list of values.
+   * Defaults to `true`.
+   */
+  allowContextList?: boolean;
+
+  /**
+   * Optional flag indicating whether the match should be case-sensitive.
+   * Defaults to `false`.
+   */
+  caseSensitive?: boolean;
+
+  /**
+   * Optional array of enumerated values to further constrain the type.
+   * Defaults to no constraint.
+   */
+  enumeratedValues?: ReadonlyArray<string>;
+
+  /**
+   * Optional {@link QualifierTypes.LiteralValueHierarchyDecl | hierarchy declaration}
+   * of literal values to use for matching. If not provided, no hierarchy will be used.
+   */
+  hierarchy?: LiteralValueHierarchyDecl<string>;
+
+  /**
+   * Global index for this qualifier type.
+   */
+  index?: number;
+}
+
+/**
+ * A {@link QualifierTypes.QualifierType | qualifier} that matches a literal value,
+ * optionally case-sensitive or matching against an ordered list of values at runtime.
+ * @public
+ */
+export class LiteralQualifierType extends QualifierType {
+  /**
+   * Indicates whether the qualifier match is case-sensitive.
+   */
+  public readonly caseSensitive: boolean;
+
+  /**
+   * Optional array of enumerated values to further constrain the type.
+   */
+  public readonly enumeratedValues?: ReadonlyArray<QualifierConditionValue>;
+
+  /**
+   * Optional {@link QualifierTypes.LiteralValueHierarchy | hierarchy} of literal
+   * values to use for matching. If not provided, no hierarchy will be used.
+   */
+  public readonly hierarchy?: LiteralValueHierarchy<string>;
+
+  /**
+   * Constructs a new {@link QualifierTypes.LiteralQualifierType | LiteralQualifierType}.
+   * @param name - Optional name for the qualifier type. Defaults to 'literal'.
+   * @param caseSensitive - Optional flag indicating whether the match should be
+   * case-sensitive. Defaults to `false`.
+   * @param allowContextList - Optional flag indicating whether the context can be a
+   * list of values. Defaults to `false`.
+   * @public
+   */
+  protected constructor({
+    name,
+    caseSensitive,
+    allowContextList,
+    enumeratedValues,
+    hierarchy,
+    index
+  }: ILiteralQualifierTypeCreateParams) {
+    allowContextList = allowContextList !== false;
+    super({
+      name: name ?? 'literal',
+      allowContextList,
+      index: index !== undefined ? Convert.qualifierTypeIndex.convert(index).orThrow() : undefined
+    });
+    this.caseSensitive = caseSensitive === true;
+    this.enumeratedValues = enumeratedValues
+      ? mapResults(Array.from(enumeratedValues).map(LiteralQualifierType.toLiteralConditionValue)).orThrow()
+      : undefined;
+    if (hierarchy) {
+      /* c8 ignore next 5 - defensive coding: enumeratedValues ?? [] fallback enables open values mode */
+      this.hierarchy = LiteralValueHierarchy.create({
+        values: enumeratedValues ?? [],
+        hierarchy: hierarchy
+      }).orThrow();
+    }
+  }
+
+  /**
+   * Determines whether a value is a valid condition value for a literal qualifier.
+   * The {@link QualifierTypes.LiteralQualifierType | LiteralQualifierType} accepts
+   * any identifier as a valid condition value.
+   * @param value - The value to validate.
+   * @returns `true` if the value is a valid condition value, `false` otherwise.
+   */
+  public isValidConditionValue(value: string): value is QualifierConditionValue {
+    if (this.enumeratedValues) {
+      if (this.caseSensitive) {
+        return this.enumeratedValues.includes(value as QualifierConditionValue);
+      }
+      return this.enumeratedValues.some((v) => v.toLowerCase() === value.toLowerCase());
+    }
+    return LiteralQualifierType.isValidLiteralConditionValue(value);
+  }
+
+  /**
+   * {@inheritdoc QualifierTypes.IQualifierType.isPotentialMatch}
+   */
+  public isPotentialMatch(conditionValue: string, contextValue: string): boolean {
+    if (this.isValidConditionValue(conditionValue) && this.isValidContextValue(contextValue)) {
+      if (this._matchOne(conditionValue, contextValue, 'matches') !== NoMatch) {
+        return true;
+      }
+      if (this.hierarchy) {
+        return this.hierarchy.isAncestor(conditionValue, contextValue);
+      }
+    }
+    return false;
+  }
+
+  /**
+   * {@inheritdoc QualifierTypes.QualifierType._matchOne}
+   */
+  protected _matchOne(
+    condition: QualifierConditionValue,
+    context: QualifierContextValue,
+    __operator: ConditionOperator
+  ): QualifierMatchScore {
+    if (this.hierarchy) {
+      return this.hierarchy.match(condition, context, __operator);
+    }
+    if (this.caseSensitive) {
+      return condition === (context as string) ? PerfectMatch : NoMatch;
+    } else {
+      return condition.toLowerCase() === context.toLowerCase() ? PerfectMatch : NoMatch;
+    }
+  }
+
+  /**
+   * Creates a new {@link QualifierTypes.LiteralQualifierType | LiteralQualifierType}.
+   * @param params - Optional {@link QualifierTypes.ILiteralQualifierTypeCreateParams | parameters}
+   * to use when creating the new instance.
+   * @returns `Success` with the new {@link QualifierTypes.LiteralQualifierType | LiteralQualifierType}
+   * if successful, `Failure` with an error message otherwise.
+   * @public
+   */
+  public static create(params?: ILiteralQualifierTypeCreateParams): Result<LiteralQualifierType> {
+    return captureResult(() => new LiteralQualifierType(params ?? {}));
+  }
+
+  /**
+   * Creates a new {@link QualifierTypes.LiteralQualifierType | LiteralQualifierType} from a configuration object.
+   * @param config - The {@link QualifierTypes.Config.IQualifierTypeConfig | configuration object} containing
+   * the name, systemType, and optional literal-specific configuration including case sensitivity,
+   * enumerated values, and hierarchy information.
+   * @returns `Success` with the new {@link QualifierTypes.LiteralQualifierType | LiteralQualifierType}
+   * if successful, `Failure` with an error message otherwise.
+   * @public
+   */
+  public static createFromConfig(
+    config: Config.IQualifierTypeConfig<Config.ILiteralQualifierTypeConfig>
+  ): Result<LiteralQualifierType> {
+    const literalConfig = config.configuration ?? {};
+    return sanitizeJsonObject<ILiteralQualifierTypeCreateParams>({
+      name: config.name,
+      allowContextList: literalConfig.allowContextList === true,
+      caseSensitive: literalConfig.caseSensitive,
+      enumeratedValues: literalConfig.enumeratedValues,
+      hierarchy: literalConfig.hierarchy
+    }).onSuccess(LiteralQualifierType.create);
+  }
+
+  /**
+   * Checks if the given value is a valid literal condition value.
+   * @param from - The value to validate.
+   * @returns `true` if the value is a valid literal condition value, otherwise `false`.
+   * @public
+   */
+  public static isValidLiteralConditionValue(from: string): from is QualifierConditionValue {
+    return Validate.RegularExpressions.identifier.test(from);
+  }
+
+  /**
+   * Converts a string to a {@link QualifierConditionValue | literal condition value}.
+   * @param from - The string to convert.
+   * @returns `Success` with the converted value if valid, or `Failure` with an error
+   * message if not.
+   * @public
+   */
+  public static toLiteralConditionValue(from: string): Result<QualifierConditionValue> {
+    return LiteralQualifierType.isValidLiteralConditionValue(from)
+      ? succeed(from)
+      : fail(`${from}: not a valid literal condition value.`);
+  }
+}