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

package/src/packlets/qualifiers/qualifier.ts

@@ -0,0 +1,169 @@
+/*
+ * 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, ICollectible, Result } from '@fgv/ts-utils';
+import {
+  ConditionPriority,
+  QualifierIndex,
+  QualifierName,
+  Convert as CommonConvert,
+  QualifierContextValue,
+  QualifierConditionValue,
+  ConditionOperator
+} from '../common';
+import { QualifierType } from '../qualifier-types';
+import { IValidatedQualifierDecl } from './qualifierDecl';
+
+/**
+ * Represents a qualifier that can be used to identify the context in
+ * which a resource is used.
+ * @public
+ */
+export class Qualifier implements IValidatedQualifierDecl, ICollectible<QualifierName, QualifierIndex> {
+  /**
+   * The name of the qualifier.
+   */
+  public readonly name: QualifierName;
+
+  /**
+   * The token used to identify the qualifier in the name or
+   * path of a resource being imported.
+   */
+  public readonly token: QualifierName;
+
+  /**
+   * The {@link QualifierTypes.QualifierType | type} of the qualifier.
+   */
+  public readonly type: QualifierType;
+
+  /**
+   * Indicates whether the token is optional in the name or path of a resource being imported.
+   */
+  public readonly tokenIsOptional: boolean;
+
+  /**
+   * Optional default value for the qualifier.
+   */
+  public readonly defaultValue?: QualifierContextValue;
+
+  /**
+   * The index of the qualifier.
+   */
+  public get index(): QualifierIndex | undefined {
+    return this._collectible.index;
+  }
+
+  /**
+   * The collector key for this qualifier.
+   */
+  public get key(): QualifierName {
+    return this._collectible.key;
+  }
+
+  /**
+   * The default {@link ConditionPriority | priority} of conditions
+   * that depend on this qualifier.
+   */
+  public readonly defaultPriority: ConditionPriority;
+
+  protected readonly _collectible: Collections.Collectible<QualifierName, QualifierIndex>;
+
+  /**
+   * Constructs a new instance of a {@link Qualifiers.Qualifier | Qualifier} from the
+   * supplied {@link Qualifiers.IValidatedQualifierDecl | validated declaration}.
+   * @param name - The name of the qualifier.
+   * @param type - The {@link QualifierTypes.QualifierType | type} of the qualifier.
+   * @param defaultPriority - The default {@link ConditionPriority | priority} of conditions
+   * @public
+   */
+  protected constructor({
+    name,
+    token,
+    type,
+    defaultPriority,
+    tokenIsOptional,
+    defaultValue,
+    index
+  }: IValidatedQualifierDecl) {
+    this.name = name;
+    this.token = token;
+    this.type = type;
+    this.defaultPriority = defaultPriority;
+    this.tokenIsOptional = tokenIsOptional;
+    this.defaultValue = defaultValue;
+    this._collectible = new Collections.Collectible<QualifierName, QualifierIndex>({
+      key: name,
+      index,
+      indexConverter: CommonConvert.qualifierIndex
+    });
+  }
+
+  /**
+   * Creates a new instance of a {@link Qualifiers.Qualifier | Qualifier} from the
+   * supplied {@link Qualifiers.IValidatedQualifierDecl | validated declaration}.
+   * @param decl - The {@link Qualifiers.IValidatedQualifierDecl | validated declaration}
+   * for the new instance.
+   * @returns `Success` with the new {@link Qualifiers.Qualifier | Qualifier} if successful,
+   * `Failure` with an error message otherwise.
+   * @public
+   */
+  public static create(decl: IValidatedQualifierDecl): Result<Qualifier> {
+    return captureResult(() => new Qualifier(decl));
+  }
+
+  /**
+   * Sets the index of this qualifier.  Once set, the index cannot be changed.
+   * @param index - The index to set.
+   * @returns `Success` with the index if successful, `Failure` with an error message otherwise.
+   */
+  public setIndex(index: QualifierIndex): Result<QualifierIndex> {
+    return this._collectible.setIndex(index);
+  }
+
+  /**
+   * {@inheritdoc QualifierTypes.QualifierType.isValidContextValue}
+   */
+  public isValidContextValue(value: string): value is QualifierContextValue {
+    return this.type.isValidContextValue(value);
+  }
+
+  /**
+   * {@inheritdoc QualifierTypes.QualifierType.isValidConditionValue}
+   */
+  public isValidConditionValue(value: string): value is QualifierConditionValue {
+    return this.type.isValidConditionValue(value);
+  }
+
+  /**
+   * {@inheritdoc QualifierTypes.QualifierType.validateCondition}
+   */
+  public validateCondition(value: string, operator?: ConditionOperator): Result<QualifierConditionValue> {
+    return this.type.validateCondition(value, operator);
+  }
+
+  /**
+   * {@inheritdoc QualifierTypes.QualifierType.validateContextValue}
+   */
+  public validateContextValue(value: string): Result<QualifierContextValue> {
+    return this.type.validateContextValue(value);
+  }
+}

package/src/packlets/qualifiers/qualifierCollector.ts

@@ -0,0 +1,194 @@
+/*
+ * 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 {
+  captureResult,
+  Collections,
+  failWithDetail,
+  Result,
+  fail,
+  succeed,
+  succeedWithDetail,
+  ValidatingConvertingCollector
+} from '@fgv/ts-utils';
+import { IQualifierDecl, IValidatedQualifierDecl } from './qualifierDecl';
+import { QualifierName } from '../common';
+import { Qualifier } from './qualifier';
+import { IQualifierDeclConvertContext, qualifierDecl, validatedQualifierDecl } from './convert';
+import { ReadOnlyQualifierTypeCollector } from '../qualifier-types';
+
+/**
+ * Readonly version of {@link Qualifiers.QualifierCollector | QualifierCollector}.
+ * @public
+ */
+export interface IReadOnlyQualifierCollector extends Collections.IReadOnlyValidatingCollector<Qualifier> {
+  /**
+   * {@inheritdoc Qualifiers.QualifierCollector.qualifierTypes}
+   */
+  readonly qualifierTypes: ReadOnlyQualifierTypeCollector;
+
+  /**
+   * Gets a {@link Qualifiers.Qualifier | qualifier} by name or token.
+   * @param nameOrToken - The name or token of the qualifier to retrieve.
+   * @returns `Success` with the qualifier if found, or `Failure` if not.
+   */
+  getByNameOrToken(nameOrToken: string): Result<Qualifier>;
+
+  /**
+   * Checks if a qualifier with a given name or token is in the collection.
+   * @param nameOrToken - The name or token of the qualifier to check.
+   * @returns `true` if the qualifier is in the collection, `false` if not.
+   */
+  hasNameOrToken(nameOrToken: string): boolean;
+}
+
+/**
+ * Parameters for creating a new {@link Qualifiers.QualifierCollector}.
+ * @public
+ */
+export interface IQualifierCollectorCreateParams {
+  /**
+   * The {@link QualifierTypes.QualifierTypeCollector | qualifier types} used to
+   * create {@link Qualifiers.Qualifier | qualifiers} from {@link Qualifiers.IQualifierDecl | declarations}.
+   */
+  qualifierTypes: ReadOnlyQualifierTypeCollector;
+
+  /**
+   * Optional list of {@link Qualifiers.IQualifierDecl | declarations} for the qualifiers to add to the collection
+   * upon creation.
+   */
+  qualifiers?: IQualifierDecl[];
+}
+
+/**
+ * Collects {@link Qualifiers.Qualifier | Qualifiers} from {@link Qualifiers.IQualifierDecl | declarations},
+ * with strongly-typed ({@link QualifierName | QualifierName} and {@link QualifierIndex | QualifierIndex}) key
+ * and index.
+ * @public
+ */
+export class QualifierCollector
+  extends ValidatingConvertingCollector<Qualifier, IQualifierDecl>
+  implements IReadOnlyQualifierCollector
+{
+  /**
+   * The {@link QualifierTypes.QualifierTypeCollector | qualifier types} that this collector uses.
+   */
+  public qualifierTypes: ReadOnlyQualifierTypeCollector;
+
+  /**
+   * Constructor for a {@link Qualifiers.QualifierCollector | QualifierCollector} object.
+   * @param params - Parameters for creating the collector.
+   * @public
+   */
+  protected constructor(params: IQualifierCollectorCreateParams) {
+    super({
+      factory: (k, i, v) => this._qualifierFactory(k, i, v),
+      converters: new Collections.KeyValueConverters({
+        key: Common.Convert.qualifierName,
+        value: qualifierDecl
+      })
+    });
+    this.qualifierTypes = params.qualifierTypes;
+    /* c8 ignore next 1 - coverage misses the branch intermittently */
+    params.qualifiers?.forEach((q) => this.validating.add(q.name, q).orThrow());
+  }
+
+  /**
+   * Creates a new {@link Qualifiers.QualifierCollector | QualifierCollector} object.
+   * @param params - {@link Qualifiers.IQualifierCollectorCreateParams | Parameters} for creating a new {@link Qualifiers.QualifierCollector | QualifierCollector}.
+   * @returns `Success` with the new collector if successful, or `Failure` if not.
+   */
+  public static create(params: IQualifierCollectorCreateParams): Result<QualifierCollector> {
+    return captureResult(() => new QualifierCollector(params));
+  }
+
+  /**
+   * {@inheritdoc Qualifiers.IReadOnlyQualifierCollector.getByNameOrToken}
+   */
+  public getByNameOrToken(nameOrToken: string): Result<Qualifier> {
+    return this.validating.get(nameOrToken).onFailure((message) => {
+      for (const q of this.values()) {
+        if (q.token === nameOrToken) {
+          return succeedWithDetail(q, 'success');
+        }
+      }
+      return failWithDetail(`Qualifier token '${nameOrToken}' not found`, 'not-found');
+    });
+  }
+
+  /**
+   * {@inheritdoc Qualifiers.IReadOnlyQualifierCollector.hasNameOrToken}
+   */
+  public hasNameOrToken(nameOrToken: string): boolean {
+    /* c8 ignore next 3 - functional code path tested but coverage intermittently missed */
+    if (this.validating.has(nameOrToken)) {
+      return true;
+    }
+    for (const q of this.values()) {
+      /* c8 ignore next 3 - functional code path tested but coverage intermittently missed */
+      if (q.token === nameOrToken) {
+        return true;
+      }
+    }
+    return false;
+  }
+
+  /**
+   * Gets a read-only view of this collector.
+   * @returns A read-only view of this collector.
+   */
+  public toReadOnly(): IReadOnlyQualifierCollector {
+    return this;
+  }
+
+  /**
+   * Factory method for creating a {@link Qualifiers.Qualifier | Qualifier} from a {@link Qualifiers.IQualifierDecl | declaration}.
+   * @param __key - The key for the qualifier.
+   * @param index - The index of the qualifier.
+   * @param decl - The {@link Qualifiers.IQualifierDecl | declaration} for the qualifier.
+   * @returns `Success` with the new {@link Qualifiers.Qualifier | Qualifier} if successful, or `Failure` if not.
+   * @public
+   */
+  protected _qualifierFactory(__key: QualifierName, index: number, decl: IQualifierDecl): Result<Qualifier> {
+    const convertContext: IQualifierDeclConvertContext = {
+      qualifierTypes: this.qualifierTypes,
+      qualifierIndex: index
+    };
+    return validatedQualifierDecl
+      .convert(decl, convertContext)
+      .onSuccess((validated) => {
+        /* c8 ignore next 9 - coverage intermittently misses this block */
+        if (this.hasNameOrToken(validated.token)) {
+          return fail<IValidatedQualifierDecl>(
+            `Qualifier token '${validated.token}' is not unique or collides with name`
+          );
+        } else if (this.hasNameOrToken(validated.name)) {
+          return fail<IValidatedQualifierDecl>(
+            `Qualifier name '${validated.name}' is not unique or collides with token`
+          );
+        }
+        return succeed(validated);
+      })
+      .onSuccess(Qualifier.create);
+  }
+}

package/src/packlets/qualifiers/qualifierDecl.ts

@@ -0,0 +1,80 @@
+/*
+ * 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 { ConditionPriority, QualifierContextValue, QualifierIndex, QualifierName } from '../common';
+import { QualifierType } from '../qualifier-types';
+
+/**
+ * Simple declaration for a {@link Qualifiers.Qualifier | Qualifier}.
+ * @public
+ */
+export interface IQualifierDecl {
+  name: string;
+  typeName: string;
+  defaultPriority: number;
+  token?: string;
+  tokenIsOptional?: boolean;
+  defaultValue?: string;
+}
+
+/**
+ * Validated declaration for a {@link Qualifiers.Qualifier | Qualifier}.
+ * @public
+ */
+export interface IValidatedQualifierDecl {
+  /**
+   * The name of the qualifier.
+   */
+  name: QualifierName;
+
+  /**
+   * The token used to identify the qualifier in the name or
+   * path of a resource being imported.
+   */
+  token: QualifierName;
+
+  /**
+   * The {@link QualifierTypes.QualifierType | type} of the qualifier.
+   */
+  type: QualifierType;
+
+  /**
+   * The default {@link ConditionPriority | priority} of conditions
+   * that depend on this qualifier.
+   */
+  defaultPriority: ConditionPriority;
+
+  /**
+   * Indicates whether the token is optional when parsing a resource token.
+   */
+  tokenIsOptional: boolean;
+
+  /**
+   * Optional default value for the qualifier.
+   */
+  defaultValue?: QualifierContextValue;
+
+  /**
+   * Index of the qualifier.
+   */
+  index: QualifierIndex | undefined;
+}

package/src/packlets/qualifiers/qualifierDefaultValueDecls.ts

@@ -0,0 +1,57 @@
+/*
+ * 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 { QualifierContextValue, QualifierName } from '../common';
+import { Qualifier } from './qualifier';
+
+/**
+ * Non-validated declaration of a single qualifier default value.
+ * @public
+ */
+export interface IQualifierDefaultValueDecl {
+  qualifier: string;
+  value: string;
+}
+
+/**
+ * Non-validated declaration of qualifier default values, consisting of named
+ * default values.
+ * @public
+ */
+export type IQualifierDefaultValuesDecl = Record<string, string>;
+
+/**
+ * Validated declaration of a single qualifier default value.
+ * @public
+ */
+export interface IValidatedQualifierDefaultValueDecl {
+  qualifier: Qualifier;
+  value: QualifierContextValue;
+}
+
+/**
+ * Validated declaration of qualifier default values, a record with strongly-typed
+ * {@link QualifierName | qualifier names} as keys and
+ * {@link QualifierContextValue | qualifier context values} as values.
+ * @public
+ */
+export type IValidatedQualifierDefaultValuesDecl = Record<QualifierName, QualifierContextValue>;