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

package/src/packlets/import/importers/jsonImporter.ts

@@ -0,0 +1,133 @@
+/*
+ * 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, DetailedResult, failWithDetail, Result, succeed } from '@fgv/ts-utils';
+import { IImporter, ImporterResultDetail } from './importer';
+import { ResourceManagerBuilder } from '../../resources';
+import { IImportable, IImportableJson, Importable, isImportable } from '../importable';
+import * as ResourceJson from '../../resource-json';
+
+/**
+ * {@link Import.Importers.IImporter | Importer} implementation which imports resources from a JSON object.
+ * @public
+ */
+export class JsonImporter implements IImporter {
+  /**
+   * {@inheritdoc Import.Importers.IImporter.types}
+   */
+  public readonly types: ReadonlyArray<string> = ['json'];
+
+  /**
+   * Protected {@link Import.Importers.JsonImporter | JsonImporter} constructor for derived classes.
+   */
+  protected constructor() {}
+
+  /**
+   * Creates a new {@link Import.Importers.JsonImporter | JsonImporter} instance.
+   * @returns `Success` with the new {@link Import.Importers.JsonImporter | JsonImporter} if successful,
+   * `Failure` otherwise.
+   */
+  public static create(): Result<JsonImporter> {
+    return captureResult(() => new JsonImporter());
+  }
+
+  /**
+   * {@inheritdoc Import.Importers.IImporter.import}
+   */
+  public import(
+    item: IImportable,
+    manager: ResourceManagerBuilder
+  ): DetailedResult<IImportable[], ImporterResultDetail> {
+    /* c8 ignore next 1 - coverage intermittently misses the next line */
+    if (!isImportable(item) || item.type !== 'json') {
+      /* c8 ignore next 3 - functional code path tested but coverage intermittently missed */
+      const name = item.context?.baseId ?? 'unknown';
+      return failWithDetail(`${name}: not a valid JSON importable (${item.type})`, 'skipped');
+    }
+    return (
+      this._tryImportResourceCollection(item)
+        .onFailure(() => this._tryImportResourceTree(item))
+        // experimenting with this, accepting any JSON object here makes it
+        // very hard to distinguish a collection or tree with a typo from a
+        // legitimate single loose resource, which yields extremely confusing
+        // error messages. Disabled until/unless we come up with a better plan.
+        //.onFailure(() => this._tryImportResource(item, manager));
+        .onFailure(() =>
+          /* c8 ignore next 1 - defense in depth */
+          failWithDetail(`${item.context?.baseId ?? 'unknown'}: unrecognized JSON format.`, 'failed')
+        )
+    );
+  }
+
+  private _tryImportResourceCollection(
+    item: IImportableJson
+  ): DetailedResult<IImportable[], ImporterResultDetail> {
+    return ResourceJson.ResourceDeclCollection.create(item.json)
+      .onSuccess((collection) => {
+        const importable: Importable = {
+          type: 'resourceCollection',
+          collection,
+          context: item.context
+        };
+        return succeed([importable]);
+      })
+      .withDetail('skipped', 'consumed');
+  }
+
+  private _tryImportResourceTree(item: IImportableJson): DetailedResult<IImportable[], ImporterResultDetail> {
+    return ResourceJson.ResourceDeclTree.create(item.json)
+      .onSuccess((tree) => {
+        const importable: Importable = {
+          type: 'resourceTree',
+          tree,
+          context: item.context
+        };
+        return succeed([importable]);
+      })
+      .withDetail('skipped', 'consumed');
+  }
+
+  /* 
+   * This is disabled for now because it's too easy to accidentally import
+   * a single loose resource as a collection or tree, which yields extremely
+   * confusing error messages.
+
+  private _tryImportResource(
+    item: IImportableJson,
+    manager: ResourceManagerBuilder
+  ): DetailedResult<IImportable[], ImporterResultDetail> {
+    return JsonConverters.jsonObject
+      .convert(item.json)
+      .onSuccess((json) => {
+        // c8 ignore next 2 - defense in depth
+        const id = item.context?.baseId ?? '';
+        const conditions = item.context?.conditions;
+        const candidate: ResourceJson.Json.ILooseResourceCandidateDecl = { id, conditions, json };
+        return manager.addLooseCandidate(candidate);
+      })
+      .onSuccess(() => {
+        return succeed([]);
+      })
+      .withDetail('failed', 'consumed');
+  }
+  */
+}

package/src/packlets/import/importers/pathImporter.ts

@@ -0,0 +1,134 @@
+/*
+ * 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,
+  DetailedResult,
+  failWithDetail,
+  Result,
+  succeedWithDetail,
+  FileTree
+} from '@fgv/ts-utils';
+import { ResourceManagerBuilder } from '../../resources';
+import { IImportable } from '../importable';
+import { IImporter, ImporterResultDetail } from './importer';
+import { IReadOnlyQualifierCollector } from '../../qualifiers';
+import { FsItem, FsItemResultDetail } from '../fsItem';
+
+/**
+ * Parameters for creating a {@link Import.Importers.PathImporter | PathImporter}.
+ * @public
+ */
+export interface IPathImporterCreateParams {
+  qualifiers: IReadOnlyQualifierCollector;
+  tree?: FileTree.FileTree;
+  ignoreFileTypes?: string[];
+}
+
+/**
+ * {@link Import.Importers.IImporter | Importer} implementation which imports resources from a `FileTree`
+ * given a path.
+ * @public
+ */
+export class PathImporter implements IImporter {
+  /**
+   * The {@link Qualifiers.IReadOnlyQualifierCollector | qualifier collector} to use for this importer.
+   */
+  public readonly qualifiers: IReadOnlyQualifierCollector;
+
+  /**
+   * The `FileTree` from which resources will be imported.
+   */
+  public readonly tree: FileTree.FileTree;
+
+  /**
+   * The types of {@link Import.IImportable | importables} that this importer can handle.
+   */
+  public readonly types: ReadonlyArray<string> = ['path'];
+
+  /**
+   * The types of files to ignore when importing.  Any file not ignored is converted
+   * to an {@link Import.IImportableFsItem | IImportableFsItem}.
+   */
+  public readonly ignoreFileTypes: string[];
+
+  /**
+   * Protected constructor for the {@link Import.Importers.PathImporter | PathImporter}.
+   * @param params - Parameters for creating the {@link Import.Importers.PathImporter | PathImporter}.
+   */
+  protected constructor(params: IPathImporterCreateParams) {
+    this.qualifiers = params.qualifiers;
+    this.tree = params.tree ?? FileTree.forFilesystem().orThrow();
+    this.ignoreFileTypes = params.ignoreFileTypes ?? [];
+  }
+
+  /**
+   * Creates a new {@link Import.Importers.PathImporter | PathImporter}.
+   * @param params - Parameters for creating the {@link Import.Importers.PathImporter | dirPathImporter}.
+   * @returns `Success` with the new `PathImporter` if successful, `Failure` with an error message if not.
+   */
+  public static create(params: IPathImporterCreateParams): Result<PathImporter> {
+    return captureResult(() => new PathImporter(params));
+  }
+
+  /**
+   * {@inheritdoc Import.Importers.IImporter.import}
+   */
+  public import(
+    item: IImportable,
+    __manager: ResourceManagerBuilder
+  ): DetailedResult<IImportable[], ImporterResultDetail> {
+    const {
+      value: fsItem,
+      message: getTreeMessage,
+      detail: getTreeDetail
+    } = this._getFileTreeItemFromImportable(item);
+    if (getTreeMessage !== undefined) {
+      return failWithDetail(getTreeMessage, getTreeDetail === 'skipped' ? 'skipped' : 'failed');
+    }
+
+    if (fsItem.item.type === 'file' && this.ignoreFileTypes.includes(fsItem.item.extension)) {
+      return succeedWithDetail([], 'processed');
+    }
+
+    // extracted characteristics are in the fsItem so add them to the context when
+    // that is imported instead of now.
+    const context = item.context;
+
+    return succeedWithDetail([{ type: 'fsItem', item: fsItem, context }], 'processed');
+  }
+
+  /**
+   * Gets an {@link Import.FsItem | FsItem} from an {@link Import.IImportable | importable}.
+   * @param item - The importable to convert.
+   * @returns `Success` containing the `FsItem` if successful, `Failure` with an error message if not.
+   */
+  protected _getFileTreeItemFromImportable(item: IImportable): DetailedResult<FsItem, FsItemResultDetail> {
+    if (item.type === 'path') {
+      if ('path' in item && typeof item.path === 'string') {
+        return FsItem.createForPath(item.path, this.qualifiers, this.tree);
+      }
+      return failWithDetail(`malformed path importable does not contain a string path`, 'failed');
+    }
+    return failWithDetail(`${item.type}: invalid importable type for a PathImporter`, 'skipped');
+  }
+}

package/src/packlets/import/index.ts

@@ -0,0 +1,29 @@
+/*
+ * 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 './importContext';
+export * from './importable';
+export * from './fsItem';
+export * from './importManager';
+
+import * as Importers from './importers';
+export { Importers };

package/src/packlets/qualifier-types/config/convert.ts

@@ -0,0 +1,108 @@
+/*
+ * 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.
+ */
+
+/* eslint-disable @rushstack/typedef-var */
+
+import { Converters } from '@fgv/ts-utils';
+import * as Model from './json';
+
+/**
+ * A `Converter` for {@link QualifierTypes.Config.ILanguageQualifierTypeConfig | LanguageQualifierTypeConfig} objects.
+ * @returns A `Converter` for {@link QualifierTypes.Config.ILanguageQualifierTypeConfig | LanguageQualifierTypeConfig} objects.
+ * @public
+ */
+export const languageQualifierTypeConfig = Converters.strictObject<Model.ILanguageQualifierTypeConfig>({
+  allowContextList: Converters.boolean.optional()
+});
+
+/**
+ * A `Converter` for {@link QualifierTypes.Config.ITerritoryQualifierTypeConfig | TerritoryQualifierTypeConfig} objects.
+ * @returns A `Converter` for {@link QualifierTypes.Config.ITerritoryQualifierTypeConfig | TerritoryQualifierTypeConfig} objects.
+ * @public
+ */
+export const territoryQualifierTypeConfig = Converters.strictObject<Model.ITerritoryQualifierTypeConfig>({
+  allowContextList: Converters.boolean,
+  acceptLowercase: Converters.boolean.optional(),
+  allowedTerritories: Converters.arrayOf(Converters.string).optional()
+});
+
+/**
+ * A `Converter` for {@link QualifierTypes.Config.ILiteralQualifierTypeConfig | LiteralQualifierTypeConfig} objects.
+ * @returns A `Converter` for {@link QualifierTypes.Config.ILiteralQualifierTypeConfig | LiteralQualifierTypeConfig} objects.
+ * @public
+ */
+export const literalQualifierTypeConfig = Converters.strictObject<Model.ILiteralQualifierTypeConfig>({
+  allowContextList: Converters.boolean.optional(),
+  caseSensitive: Converters.boolean.optional(),
+  enumeratedValues: Converters.arrayOf(Converters.string).optional(),
+  hierarchy: Converters.recordOf(Converters.string).optional()
+});
+
+/**
+ * A `Converter` for {@link QualifierTypes.Config.ISystemLanguageQualifierTypeConfig | SystemLanguageQualifierTypeConfig} objects.
+ * @returns A `Converter` for {@link QualifierTypes.Config.ISystemLanguageQualifierTypeConfig | SystemLanguageQualifierTypeConfig} objects.
+ * @public
+ */
+export const systemLanguageQualifierTypeConfig =
+  Converters.strictObject<Model.ISystemLanguageQualifierTypeConfig>({
+    name: Converters.string,
+    systemType: Converters.literal('language'),
+    configuration: languageQualifierTypeConfig.optional()
+  });
+
+/**
+ * A `Converter` for {@link QualifierTypes.Config.ISystemTerritoryQualifierTypeConfig | SystemTerritoryQualifierTypeConfig} objects.
+ * @returns A `Converter` for {@link QualifierTypes.Config.ISystemTerritoryQualifierTypeConfig | SystemTerritoryQualifierTypeConfig} objects.
+ * @public
+ */
+export const systemTerritoryQualifierTypeConfig =
+  Converters.strictObject<Model.ISystemTerritoryQualifierTypeConfig>({
+    name: Converters.string,
+    systemType: Converters.literal('territory'),
+    configuration: territoryQualifierTypeConfig.optional()
+  });
+
+/**
+ * A `Converter` for {@link QualifierTypes.Config.ISystemLiteralQualifierTypeConfig | SystemLiteralQualifierTypeConfig} objects.
+ * @returns A `Converter` for {@link QualifierTypes.Config.ISystemLiteralQualifierTypeConfig | SystemLiteralQualifierTypeConfig} objects.
+ * @public
+ */
+export const systemLiteralQualifierTypeConfig =
+  Converters.strictObject<Model.ISystemLiteralQualifierTypeConfig>({
+    name: Converters.string,
+    systemType: Converters.literal('literal'),
+    configuration: literalQualifierTypeConfig.optional()
+  });
+
+/**
+ * A `Converter` for {@link QualifierTypes.Config.ISystemQualifierTypeConfig | SystemQualifierTypeConfig} objects.
+ * @returns A `Converter` for {@link QualifierTypes.Config.ISystemQualifierTypeConfig | SystemQualifierTypeConfig} objects.
+ * @public
+ */
+export const systemQualifierTypeConfig = Converters.discriminatedObject<Model.ISystemQualifierTypeConfig>(
+  'systemType',
+  {
+    language: systemLanguageQualifierTypeConfig,
+    territory: systemTerritoryQualifierTypeConfig,
+    literal: systemLiteralQualifierTypeConfig
+  }
+);

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

@@ -0,0 +1,27 @@
+/*
+ * 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 './json';
+
+export { Convert };

package/src/packlets/qualifier-types/config/json.ts

@@ -0,0 +1,126 @@
+/*
+ * 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 { LiteralValueHierarchyDecl } from '../literalValueHierarchy';
+
+/**
+ * Templated configuration for {@link QualifierTypes.QualifierType | qualifier type} configuration.
+ * @public
+ */
+export interface IQualifierTypeConfig<T = JsonObject> {
+  name: string;
+  systemType: string;
+  configuration?: T;
+}
+
+/**
+ * Configuration for {@link QualifierTypes.LanguageQualifierType | language qualifier type} configuration.
+ * @public
+ */
+export interface ILanguageQualifierTypeConfig {
+  allowContextList?: boolean;
+}
+
+/**
+ * Configuration for {@link QualifierTypes.TerritoryQualifierType | territory qualifier type} configuration.
+ * @public
+ */
+export interface ITerritoryQualifierTypeConfig {
+  allowContextList?: boolean;
+
+  acceptLowercase?: boolean;
+  allowedTerritories?: string[];
+
+  /**
+   * Optional {@link QualifierTypes.LiteralValueHierarchyDecl | hierarchy declaration}
+   * of territory values to use for matching. If not provided, no hierarchy will be used.
+   */
+  hierarchy?: LiteralValueHierarchyDecl<string>;
+}
+
+/**
+ * Configuration for {@link QualifierTypes.LiteralQualifierType | literal qualifier type} configuration.
+ * @public
+ */
+export interface ILiteralQualifierTypeConfig {
+  allowContextList?: boolean;
+  caseSensitive?: boolean;
+  enumeratedValues?: string[];
+  hierarchy?: LiteralValueHierarchyDecl<string>;
+}
+
+/**
+ * Discriminated configuration for {@link QualifierTypes.LanguageQualifierType | language qualifier type} configuration.
+ * @public
+ */
+export interface ISystemLanguageQualifierTypeConfig
+  extends IQualifierTypeConfig<ILanguageQualifierTypeConfig> {
+  systemType: 'language';
+}
+
+/**
+ * Discriminated configuration for {@link QualifierTypes.TerritoryQualifierType | territory qualifier type} configuration.
+ * @public
+ */
+export interface ISystemTerritoryQualifierTypeConfig
+  extends IQualifierTypeConfig<ITerritoryQualifierTypeConfig> {
+  systemType: 'territory';
+}
+
+/**
+ * Discriminated configuration for {@link QualifierTypes.LiteralQualifierType | literal qualifier type} configuration.
+ * @public
+ */
+export interface ISystemLiteralQualifierTypeConfig extends IQualifierTypeConfig<ILiteralQualifierTypeConfig> {
+  systemType: 'literal';
+}
+
+/**
+ * Discriminated configuration for {@link QualifierTypes.QualifierType | qualifier type} configuration.
+ * @public
+ */
+export type ISystemQualifierTypeConfig =
+  | ISystemLanguageQualifierTypeConfig
+  | ISystemTerritoryQualifierTypeConfig
+  | ISystemLiteralQualifierTypeConfig;
+
+/**
+ * A union of all qualifier type configurations.
+ * @public
+ */
+export type IAnyQualifierTypeConfig = IQualifierTypeConfig | ISystemQualifierTypeConfig;
+
+/**
+ * Checks if a {@link QualifierTypes.Config.IAnyQualifierTypeConfig | qualifier type configuration} is a
+ * {@link QualifierTypes.Config.ISystemQualifierTypeConfig | system qualifier type configuration}.
+ * @param config - The {@link QualifierTypes.Config.IAnyQualifierTypeConfig | qualifier type configuration} to check.
+ * @returns `true` if the configuration is a system qualifier type configuration, `false` otherwise.
+ * @public
+ */
+export function isSystemQualifierTypeConfig(
+  config: IAnyQualifierTypeConfig
+): config is ISystemQualifierTypeConfig {
+  return (
+    config.systemType === 'language' || config.systemType === 'territory' || config.systemType === 'literal'
+  );
+}

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

@@ -0,0 +1,77 @@
+/*
+ * 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 { Converter, Converters, Result, fail } from '@fgv/ts-utils';
+import { QualifierType } from './qualifierType';
+import { ReadOnlyQualifierTypeCollector } from './qualifierTypeCollector';
+import { ILiteralValueHierarchyCreateParams } from './literalValueHierarchy';
+
+/**
+ * Context necessary to convert a qualifier name or number to an instantiated
+ * {@link QualifierTypes.QualifierType}.
+ * @public
+ */
+export interface IQualifierTypeConvertContext {
+  qualifierTypes: ReadOnlyQualifierTypeCollector;
+}
+
+/**
+ * Converter for {@link QualifierTypes.QualifierType | QualifierType} objects,
+ * retrieves a {@link QualifierTypes.QualifierType | QualifierType} by name or
+ * index from a supplied {@link QualifierTypes.Convert.IQualifierTypeConvertContext | conversion context}.
+ * @public
+ */
+// eslint-disable-next-line @rushstack/typedef-var
+export const qualifierType = Converters.generic<QualifierType, IQualifierTypeConvertContext>(
+  (
+    from: unknown,
+    __self: Converter<QualifierType, IQualifierTypeConvertContext>,
+    context?: IQualifierTypeConvertContext
+  ): Result<QualifierType> => {
+    if (!context) {
+      return fail('qualifierType converter requires a context');
+    }
+    if (typeof from === 'string') {
+      return context.qualifierTypes.validating.get(from);
+    } else if (typeof from === 'number') {
+      return context.qualifierTypes.getAt(from);
+    }
+    return fail('qualifierType converter requires a string or number');
+  }
+);
+
+/**
+ * Gets a converter for {@link QualifierTypes.ILiteralValueHierarchyCreateParams | ILiteralValueHierarchyCreateParams}
+ * objects with values validated by a supplied value converter.
+ * @param valueConverter - Converter for the literal value type.
+ * @public
+ */
+export function literalValueHierarchyCreateParams<T extends string>(
+  valueConverter: Converter<T>
+): Converter<ILiteralValueHierarchyCreateParams<T>> {
+  return Converters.object<ILiteralValueHierarchyCreateParams<T>>({
+    values: Converters.arrayOf(valueConverter),
+    hierarchy: Converters.recordOf(valueConverter, {
+      keyConverter: valueConverter
+    })
+  });
+}