@fgv/ts-res 5.0.0-22 → 5.0.0-24

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

@@ -1,102 +0,0 @@
-/*
- * 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 Common from '../common';
-import {
-  Collections,
-  Result,
-  ValidatingConvertingCollector,
-  captureResult,
-  fail,
-  succeed
-} from '@fgv/ts-utils';
-import { QualifierType } from './qualifierType';
-import { QualifierTypeName } from '../common';
-
-/**
- * Parameters for creating a new {@link QualifierTypes.QualifierTypeCollector | QualifierTypeCollector}.
- * @public
- */
-export interface IQualifierTypeCollectorCreateParams {
-  /**
-   * Optional list of {@link QualifierTypes.QualifierType | QualifierTypes} to add to the collector
-   * on creation.
-   */
-  qualifierTypes?: QualifierType[];
-}
-
-/**
- * Collector for {@link QualifierTypes.QualifierType | QualifierType} objects.
- * @public
- */
-export class QualifierTypeCollector extends ValidatingConvertingCollector<QualifierType, QualifierType> {
-  /**
-   * Constructor for a {@link QualifierTypes.QualifierTypeCollector | QualifierTypeCollector} object.
-   * @param params - Optional {@link QualifierTypes.IQualifierTypeCollectorCreateParams | parameters}
-   * used to construct the collector.
-   */
-  protected constructor({ qualifierTypes }: IQualifierTypeCollectorCreateParams) {
-    super({
-      converters: new Collections.KeyValueConverters({
-        key: Common.Convert.qualifierTypeName,
-        value: QualifierTypeCollector._toQualifierType
-      }),
-      factory: QualifierTypeCollector._qualifierTypeFactory
-    });
-
-    /* c8 ignore next 1 - coverage seems to intermittently miss the branch */
-    qualifierTypes?.forEach((qt) => {
-      this.add(qt).orThrow();
-    });
-  }
-
-  /**
-   * Creates a new {@link QualifierTypes.QualifierTypeCollector | QualifierTypeCollector} object.
-   * @param params - Optional {@link QualifierTypes.IQualifierTypeCollectorCreateParams | parameters}
-   * used to create the collector.
-   * @returns `Success` with the new collector if successful, or `Failure` if not.
-   */
-  public static create(params?: IQualifierTypeCollectorCreateParams): Result<QualifierTypeCollector> {
-    /* c8 ignore next 1 - coverage seems to miss the branch intermittently */
-    params = params ?? {};
-    return captureResult(() => new QualifierTypeCollector(params));
-  }
-
-  protected static _qualifierTypeFactory(
-    key: QualifierTypeName,
-    index: number,
-    value: QualifierType
-  ): Result<QualifierType> {
-    return succeed(value);
-  }
-
-  protected static _toQualifierType(from: unknown): Result<QualifierType> {
-    return from instanceof QualifierType ? succeed(from) : fail('not a QualifierType');
-  }
-}
-
-/**
- * Interface exposing non-mutating members of a
- * {@link QualifierTypes.QualifierTypeCollector | QualifierTypeCollector}.
- * @public
- */
-export type ReadOnlyQualifierTypeCollector = Collections.IReadOnlyValidatingCollector<QualifierType>;

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

@@ -1,255 +0,0 @@
-/*
- * 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, Result, fail, succeed, mapResults } from '@fgv/ts-utils';
-import {
-  Convert,
-  NoMatch,
-  PerfectMatch,
-  QualifierConditionValue,
-  QualifierContextValue,
-  QualifierMatchScore,
-  Validate,
-  ConditionOperator
-} from '../common';
-import { QualifierType } from './qualifierType';
-import { LiteralValueHierarchy, LiteralValueHierarchyDecl } from './literalValueHierarchy';
-import * as Config from './config';
-import { sanitizeJsonObject } from '@fgv/ts-json-base';
-
-/**
- * Parameters used to create a new {@link QualifierTypes.TerritoryQualifierType | TerritoryQualifierType} instance.
- * @public
- */
-export interface ITerritoryQualifierTypeCreateParams {
-  /**
-   * {@inheritdoc QualifierTypes.IQualifierTypeCreateParams.name}
-   */
-  name?: string;
-
-  /**
-   * {@inheritdoc QualifierTypes.IQualifierTypeCreateParams.allowContextList}
-   */
-  allowContextList?: boolean;
-
-  /**
-   * {@inheritdoc QualifierTypes.IQualifierTypeCreateParams.index}
-   */
-  index?: number;
-
-  /**
-   * Optional array enumerating allowed territories to further constrain the type.
-   */
-  allowedTerritories?: string[];
-
-  /**
-   * Flag indicating whether the qualifier type should accept lowercase territory codes.
-   * Defaults to `false`.
-   */
-  acceptLowercase?: boolean;
-
-  /**
-   * Optional {@link QualifierTypes.LiteralValueHierarchyDecl | hierarchy declaration}
-   * of territory values to use for matching. If not provided, no hierarchy will be used.
-   */
-  hierarchy?: LiteralValueHierarchyDecl<string>;
-}
-
-/**
- * Qualifier type for territory values. Territories are two-letter ISO-3166-2
- * Alpha-2 country codes. Canonical territory codes are uppercase, but this
- * implementation handles incorrect casing.
- * @public
- */
-export class TerritoryQualifierType extends QualifierType {
-  /**
-   * Optional array enumerating allowed territories to further constrain the type.
-   */
-  public readonly allowedTerritories?: ReadonlyArray<QualifierConditionValue>;
-
-  /**
-   * Flag indicating whether the qualifier type should accept lowercase territory codes.
-   * Defaults to `false`.
-   */
-  public readonly acceptLowercase: boolean;
-
-  /**
-   * Optional {@link QualifierTypes.LiteralValueHierarchy | hierarchy} of territory
-   * values to use for matching. If not provided, no hierarchy will be used.
-   */
-  public readonly hierarchy?: LiteralValueHierarchy<string>;
-
-  /**
-   * Creates a new {@link QualifierTypes.TerritoryQualifierType | TerritoryQualifierType} instance.
-   * @public
-   */
-  protected constructor({
-    acceptLowercase,
-    allowedTerritories,
-    allowContextList,
-    name,
-    index,
-    hierarchy
-  }: ITerritoryQualifierTypeCreateParams) {
-    /* c8 ignore next 7 - coverage seems to be missing coalescing branches */
-    name = name ?? 'territory';
-    const validIndex = index !== undefined ? Convert.qualifierTypeIndex.convert(index).orThrow() : undefined;
-    const validTerritories =
-      allowedTerritories !== undefined
-        ? mapResults(
-            allowedTerritories.map((t) => TerritoryQualifierType.toTerritoryConditionValue(t.toUpperCase()))
-          ).orThrow()
-        : undefined;
-
-    allowContextList = allowContextList === true;
-    super({
-      name: name,
-      allowContextList,
-      index: validIndex
-    });
-    this.allowedTerritories = validTerritories;
-    this.acceptLowercase = acceptLowercase === true;
-
-    if (hierarchy) {
-      /* c8 ignore next 5 - defensive coding: allowedTerritories ?? [] fallback enables open values mode */
-      this.hierarchy = LiteralValueHierarchy.create({
-        values: allowedTerritories ?? [],
-        hierarchy: hierarchy
-      }).orThrow();
-    }
-  }
-
-  /**
-   * {@inheritdoc QualifierTypes.QualifierType.isValidConditionValue}
-   */
-  public isValidConditionValue(value: string): value is QualifierConditionValue {
-    const normalized = this.acceptLowercase ? value.toUpperCase() : value;
-
-    if (!TerritoryQualifierType.isValidTerritoryConditionValue(normalized)) {
-      return false;
-    }
-    if (this.allowedTerritories !== undefined) {
-      return this.allowedTerritories.includes(normalized);
-    }
-    return true;
-  }
-
-  /**
-   * Creates a new {@link QualifierTypes.TerritoryQualifierType | TerritoryQualifierType} instance.
-   * @param params - Optional {@link QualifierTypes.ITerritoryQualifierTypeCreateParams | parameters}
-   * to use when creating the instance.
-   * @returns `Success` with the new {@link QualifierTypes.TerritoryQualifierType | TerritoryQualifierType}
-   * if successful, `Failure` with an error message otherwise.
-   * @public
-   */
-  public static create(params?: ITerritoryQualifierTypeCreateParams): Result<TerritoryQualifierType> {
-    /* c8 ignore next 1 - coverage having problems with conditional branches */
-    params = params ?? {};
-    return captureResult(() => new TerritoryQualifierType(params));
-  }
-
-  /**
-   * Creates a new {@link QualifierTypes.TerritoryQualifierType | TerritoryQualifierType} from a configuration object.
-   * @param config - The {@link QualifierTypes.Config.IQualifierTypeConfig | configuration object} containing
-   * the name, systemType, and optional territory-specific configuration including allowed territories and hierarchy.
-   * @returns `Success` with the new {@link QualifierTypes.TerritoryQualifierType | TerritoryQualifierType}
-   * if successful, `Failure` with an error message otherwise.
-   * @public
-   */
-  public static createFromConfig(
-    config: Config.IQualifierTypeConfig<Config.ITerritoryQualifierTypeConfig>
-  ): Result<TerritoryQualifierType> {
-    const territoryConfig = config.configuration ?? {};
-    return sanitizeJsonObject<ITerritoryQualifierTypeCreateParams>({
-      name: config.name,
-      allowContextList: territoryConfig.allowContextList === true,
-      allowedTerritories: territoryConfig.allowedTerritories,
-      acceptLowercase: territoryConfig.acceptLowercase === true,
-      hierarchy: territoryConfig.hierarchy
-    }).onSuccess(TerritoryQualifierType.create);
-  }
-
-  /**
-   * {@inheritdoc QualifierTypes.QualifierType._matchOne}
-   */
-  protected _matchOne(
-    condition: QualifierConditionValue,
-    context: QualifierContextValue,
-    __operator?: ConditionOperator
-  ): QualifierMatchScore {
-    if (this.isValidConditionValue(condition) && this.isValidContextValue(context)) {
-      // Normalize to uppercase for territory codes
-      const normalizedCondition = condition.toUpperCase();
-      const normalizedContext = context.toUpperCase() as QualifierContextValue;
-
-      if (normalizedCondition === normalizedContext) {
-        return PerfectMatch;
-      }
-
-      if (this.hierarchy) {
-        return this.hierarchy.match(
-          normalizedCondition as QualifierConditionValue,
-          normalizedContext as QualifierContextValue,
-          __operator
-        );
-      }
-    }
-    return NoMatch;
-  }
-
-  /**
-   * Determines whether a value is a valid condition value for a territory qualifier.
-   * @param value - The value to validate.
-   * @param acceptLowercase - Flag indicating whether the qualifier type should accept lowercase territory codes.
-   * Defaults to `false`.
-   * @returns `true` if the value is a valid condition value, `false` otherwise.
-   * @public
-   */
-  public static isValidTerritoryConditionValue(
-    value: string,
-    acceptLowercase?: boolean
-  ): value is QualifierConditionValue {
-    if (acceptLowercase !== true && value !== value.toUpperCase()) {
-      return false;
-    }
-    return Validate.RegularExpressions.territoryCode.test(value.toUpperCase());
-  }
-
-  /**
-   * Converts a string value to a territory condition value.
-   * @param value - The value to convert.
-   * @param acceptLowercase - Flag indicating whether the qualifier type should accept lowercase territory codes.
-   * Defaults to `false`.
-   * @returns `Success` with the converted value if successful, `Failure` with an error
-   * message otherwise.
-   * @public
-   */
-  public static toTerritoryConditionValue(
-    value: string,
-    acceptLowercase?: boolean
-  ): Result<QualifierConditionValue> {
-    const normalized = value.toUpperCase();
-    return TerritoryQualifierType.isValidTerritoryConditionValue(normalized, acceptLowercase)
-      ? succeed(normalized)
-      : fail(`${value}: not a valid territory code`);
-  }
-}

package/src/packlets/qualifiers/convert/decls.ts

@@ -1,90 +0,0 @@
-/*
- * 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 { Converters, populateObject, Result, fail, succeed } from '@fgv/ts-utils';
-import { IQualifierDecl, IValidatedQualifierDecl } from '../qualifierDecl';
-import { Validate } from '../../common';
-import { ReadOnlyQualifierTypeCollector } from '../../qualifier-types';
-
-/* eslint-disable @rushstack/typedef-var */
-
-/**
- * Converter for a {@link Qualifiers.IQualifierDecl | qualifier declaration}.
- * @public
- */
-export const qualifierDecl = Converters.strictObject<IQualifierDecl>({
-  name: Converters.string,
-  typeName: Converters.string,
-  defaultPriority: Converters.number,
-  token: Converters.string.optional(),
-  tokenIsOptional: Converters.boolean.optional(),
-  defaultValue: Converters.string.optional()
-});
-
-/**
- * Context necessary to convert a {@link Qualifiers.IValidatedQualifierDecl | validated qualifier declaration}.
- * @public
- */
-export interface IQualifierDeclConvertContext {
-  readonly qualifierTypes: ReadOnlyQualifierTypeCollector;
-  qualifierIndex?: number;
-}
-
-/**
- * Converter which constructs a {@link Qualifiers.IValidatedQualifierDecl | validated qualifier declaration}
- * from a {@link Qualifiers.IQualifierDecl | qualifier declaration}, instantiating qualifier types by name
- * from a supplied {@link Qualifiers.Convert.IQualifierDeclConvertContext | conversion context}.
- * @public
- */
-export const validatedQualifierDecl = Converters.generic<
-  IValidatedQualifierDecl,
-  IQualifierDeclConvertContext
->((from: unknown, __self, context?: IQualifierDeclConvertContext): Result<IValidatedQualifierDecl> => {
-  /* c8 ignore next 7  - this is tested but code coverage is losing its mind */
-  if (context === undefined) {
-    return fail('validatedQualifierDecl converter requires a context');
-  }
-  const validatedIndexResult =
-    context.qualifierIndex !== undefined
-      ? Validate.toQualifierIndex(context.qualifierIndex)
-      : succeed(undefined);
-
-  return qualifierDecl.convert(from).onSuccess((decl) => {
-    return context.qualifierTypes.validating.get(decl.typeName).asResult.onSuccess((type) => {
-      return populateObject<IValidatedQualifierDecl>({
-        name: () => Validate.toQualifierName(decl.name),
-        token: () => Validate.toQualifierName(decl.token ?? decl.name),
-        tokenIsOptional: () => succeed(decl.tokenIsOptional === true),
-        type: () => succeed(type),
-        defaultPriority: () => Validate.toConditionPriority(decl.defaultPriority),
-        defaultValue: () =>
-          decl.defaultValue ? type.validateContextValue(decl.defaultValue) : succeed(undefined),
-        index: () => validatedIndexResult
-      }).onSuccess((validated) => {
-        if (context.qualifierIndex !== undefined) {
-          context.qualifierIndex++;
-        }
-        return succeed(validated);
-      });
-    });
-  });
-});

package/src/packlets/qualifiers/convert/index.ts

@@ -1,24 +0,0 @@
-/*
- * 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.
- */
-
-export * from './decls';
-export * from './qualifier';

package/src/packlets/qualifiers/convert/qualifier.ts

@@ -1,55 +0,0 @@
-/*
- * 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 { Converters, Result, fail } from '@fgv/ts-utils';
-import { IReadOnlyQualifierCollector } from '../qualifierCollector';
-import { Qualifier } from '../qualifier';
-
-/* eslint-disable @rushstack/typedef-var */
-
-/**
- * Context necessary to convert a string or number to a
- * {@link Qualifiers.Qualifier | Qualifier} object.
- * @public
- */
-export interface IQualifierConvertContext {
-  qualifiers: IReadOnlyQualifierCollector;
-}
-
-/**
- * Converter which choose a qualifier by name or number from a
- * supplied {@link Qualifiers.Convert.IQualifierConvertContext | conversion context}.
- * @public
- */
-export const qualifier = Converters.generic<Qualifier, IQualifierConvertContext>(
-  (from: unknown, __self, context?: IQualifierConvertContext): Result<Qualifier> => {
-    if (context === undefined) {
-      return fail('qualifier converter requires a context');
-    }
-    if (typeof from === 'string') {
-      return context.qualifiers.validating.get(from);
-    } else if (typeof from === 'number') {
-      return context.qualifiers.getAt(from);
-    }
-    return fail('qualifier converter requires a string or number');
-  }
-);

package/src/packlets/qualifiers/index.ts

@@ -1,31 +0,0 @@
-/*
- * 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 Convert from './convert';
-
-export * from './qualifier';
-export * from './qualifierDecl';
-export * from './qualifierCollector';
-export * from './qualifierDefaultValueDecls';
-export * from './qualifierDefaultValueToken';
-
-export { Convert };