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

package/src/packlets/bcp47/match/similarity.ts

@@ -0,0 +1,243 @@
+/*
+ * Copyright (c) 2022 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 Iana from '../../iana';
+import * as Unsd from '../../unsd';
+
+import { DefaultRegistries, OverridesRegistry } from '../overrides';
+
+import { GlobalRegion } from '../common';
+import { LanguageTag } from '../languageTag';
+import { tagSimilarity } from './common';
+
+/**
+ * Helper to compare two language tags to determine how closely related they are,
+ * applying normalization and language semantics as appropriate.
+ * @public
+ */
+export class LanguageSimilarityMatcher {
+  public iana: Iana.LanguageRegistries;
+  public unsd: Unsd.RegionCodes;
+  public overrides: OverridesRegistry;
+
+  public constructor(iana?: Iana.LanguageRegistries) {
+    /* c8 ignore next */
+    this.iana = iana ?? Iana.DefaultRegistries.languageRegistries;
+    this.unsd = Unsd.DefaultRegistries.regionCodes;
+    this.overrides = DefaultRegistries.overridesRegistry;
+  }
+
+  public matchLanguageTags(t1: LanguageTag, t2: LanguageTag): number {
+    // no primary tag is either all private or grandfathered, which must match
+    // exactly.
+    if (!t1.subtags.primaryLanguage || !t2.subtags.primaryLanguage) {
+      return t1.toString().toLowerCase() === t2.toString().toLowerCase()
+        ? tagSimilarity.exact
+        : tagSimilarity.none;
+    }
+
+    let quality = this.matchPrimaryLanguage(t1, t2);
+    quality = quality > tagSimilarity.none ? Math.min(this.matchExtlang(t1, t2), quality) : quality;
+    quality = quality > tagSimilarity.none ? Math.min(this.matchScript(t1, t2), quality) : quality;
+    quality = quality > tagSimilarity.none ? Math.min(this.matchRegion(t1, t2), quality) : quality;
+    quality = quality > tagSimilarity.none ? Math.min(this.matchVariants(t1, t2), quality) : quality;
+    quality = quality > tagSimilarity.none ? Math.min(this.matchExtensions(t1, t2), quality) : quality;
+    quality = quality > tagSimilarity.none ? Math.min(this.matchPrivateUseTags(t1, t2), quality) : quality;
+
+    return quality;
+  }
+
+  public matchPrimaryLanguage(lt1: LanguageTag, lt2: LanguageTag): number {
+    /* c8 ignore next 2 */
+    const l1 = lt1.subtags.primaryLanguage?.toLowerCase();
+    const l2 = lt2.subtags.primaryLanguage?.toLowerCase();
+
+    if (l1 === l2) {
+      return tagSimilarity.exact;
+    }
+
+    if (lt1.isUndetermined || lt2.isUndetermined) {
+      return tagSimilarity.undetermined;
+    }
+
+    return tagSimilarity.none;
+  }
+
+  public matchExtlang(lt1: LanguageTag, lt2: LanguageTag): number {
+    if (lt1.subtags.extlangs?.length !== lt2.subtags.extlangs?.length) {
+      return tagSimilarity.none;
+    }
+
+    if (lt1.subtags.extlangs) {
+      for (let i = 0; i < lt1.subtags.extlangs.length; i++) {
+        if (lt1.subtags.extlangs[i].toLowerCase() !== lt2.subtags.extlangs![i].toLowerCase()) {
+          return tagSimilarity.none;
+        }
+      }
+    }
+
+    return tagSimilarity.exact;
+  }
+
+  public matchScript(lt1: LanguageTag, lt2: LanguageTag): number {
+    const s1 = lt1.effectiveScript?.toLowerCase();
+    const s2 = lt2.effectiveScript?.toLowerCase();
+
+    if (s1 === s2) {
+      return tagSimilarity.exact;
+    }
+
+    if (lt1.isUndetermined || lt2.isUndetermined) {
+      return tagSimilarity.undetermined;
+    }
+
+    return tagSimilarity.none;
+  }
+
+  public matchRegion(lt1: LanguageTag, lt2: LanguageTag): number {
+    const r1 = lt1.subtags.region?.toUpperCase() as Iana.LanguageSubtags.RegionSubtag;
+    const r2 = lt2.subtags.region?.toUpperCase() as Iana.LanguageSubtags.RegionSubtag;
+
+    if (r1 === r2) {
+      return tagSimilarity.exact;
+    }
+
+    // region 001 is equivalent to neutral (no region)
+    if (r1 === GlobalRegion || r2 === GlobalRegion) {
+      // if one tag is 001 and the other in neutral, exact match
+      // otherwise, one tag is 001 so neutral region match
+      return !r1 || !r2 ? tagSimilarity.exact : tagSimilarity.neutralRegion;
+    }
+
+    if (!r1 || !r2) {
+      return tagSimilarity.neutralRegion;
+    }
+
+    // macro-region match
+    const r1IsMacroRegion = Iana.Validate.unM49RegionCode.isWellFormed(r1);
+    const r2IsMacroRegion = Iana.Validate.unM49RegionCode.isWellFormed(r2);
+    if (r1IsMacroRegion || r2IsMacroRegion) {
+      let contained: Unsd.ICountryOrArea | Unsd.Region | undefined;
+      let container: Unsd.Region | undefined;
+      if (r1IsMacroRegion) {
+        container = this.unsd.regions.tryGetRegion(r1 as unknown as Iana.Model.UnM49RegionCode);
+        contained =
+          this.unsd.areas.tryGetAlpha2Area(r2 as unknown as Iana.Model.IsoAlpha2RegionCode) ??
+          this.unsd.tryGetRegionOrArea(r2 as unknown as Iana.Model.UnM49RegionCode);
+      } else {
+        container = this.unsd.regions.tryGetRegion(r2 as unknown as Iana.Model.UnM49RegionCode);
+        contained = this.unsd.areas.tryGetAlpha2Area(r1 as unknown as Iana.Model.IsoAlpha2RegionCode);
+      }
+      if (container && contained) {
+        if (this.unsd.getIsContained(container, contained)) {
+          return tagSimilarity.macroRegion;
+        }
+
+        // if they're both regions, also check to see if the second region contains the
+        // first
+        if (contained.tier !== 'area' && this.unsd.getIsContained(contained, container)) {
+          return tagSimilarity.macroRegion;
+        }
+      }
+    }
+
+    /* c8 ignore next 6 */
+    const o1 = this.overrides.overrides.get(
+      lt1.subtags.primaryLanguage?.toLowerCase() as Iana.LanguageSubtags.LanguageSubtag
+    );
+    const o2 = this.overrides.overrides.get(
+      lt2.subtags.primaryLanguage?.toLowerCase() as Iana.LanguageSubtags.LanguageSubtag
+    );
+
+    // orthographic affinity
+    if (o1 && o2) {
+      /* c8 ignore next 2 */
+      const a1 = o1.affinity?.get(r1) ?? o1.defaultAffinity;
+      const a2 = o2.affinity?.get(r2) ?? o2.defaultAffinity;
+      if (a1 && a2 && a1 === a2) {
+        if (r1 === a1.toUpperCase() || r2 === a2.toUpperCase()) {
+          return tagSimilarity.preferredAffinity;
+        }
+        return tagSimilarity.affinity;
+      }
+    }
+
+    // preferred region
+    if (o1?.preferredRegion === r1 || o2?.preferredRegion === r2) {
+      return tagSimilarity.preferredRegion;
+    }
+
+    return tagSimilarity.sibling;
+  }
+
+  public matchVariants(lt1: LanguageTag, lt2: LanguageTag): number {
+    if (lt1.subtags.variants?.length !== lt2.subtags.variants?.length) {
+      return tagSimilarity.region;
+    }
+
+    if (lt1.subtags.variants) {
+      for (let i = 0; i < lt1.subtags.variants.length; i++) {
+        if (lt1.subtags.variants[i].toLowerCase() !== lt2.subtags.variants![i].toLowerCase()) {
+          return tagSimilarity.region;
+        }
+      }
+    }
+
+    return tagSimilarity.exact;
+  }
+
+  public matchExtensions(lt1: LanguageTag, lt2: LanguageTag): number {
+    if (lt1.subtags.extensions?.length !== lt2.subtags.extensions?.length) {
+      return tagSimilarity.variant;
+    }
+
+    if (lt1.subtags.extensions) {
+      for (let i = 0; i < lt1.subtags.extensions.length; i++) {
+        if (
+          lt1.subtags.extensions[i].singleton.toLowerCase() !==
+            lt2.subtags.extensions![i].singleton.toLowerCase() ||
+          lt1.subtags.extensions[i].value.toLowerCase() !== lt2.subtags.extensions![i].value.toLowerCase()
+        ) {
+          return tagSimilarity.variant;
+        }
+      }
+    }
+
+    return tagSimilarity.exact;
+  }
+
+  public matchPrivateUseTags(lt1: LanguageTag, lt2: LanguageTag): number {
+    if (lt1.subtags.privateUse?.length !== lt2.subtags.privateUse?.length) {
+      return tagSimilarity.variant;
+    }
+
+    if (lt1.subtags.privateUse) {
+      for (let i = 0; i < lt1.subtags.privateUse.length; i++) {
+        if (lt1.subtags.privateUse[i].toLowerCase() !== lt2.subtags.privateUse![i].toLowerCase()) {
+          return tagSimilarity.variant;
+        }
+      }
+    }
+
+    return tagSimilarity.exact;
+  }
+}

package/src/packlets/bcp47/normalization/baseNormalizer.ts

@@ -0,0 +1,146 @@
+/*
+ * Copyright (c) 2022 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 Iana from '../../iana';
+
+import { Result, allSucceed, fail, mapResults, populateObject, succeed } from '@fgv/ts-utils';
+import { ExtensionSingleton, ExtensionSubtag } from '../bcp47Subtags/model';
+import { IExtensionSubtagValue, ISubtags, subtagsToString } from '../common';
+import { TagNormalization } from './common';
+
+/**
+ * @public
+ */
+export interface ITagNormalizer {
+  readonly normalization: TagNormalization;
+
+  processSubtags(subtags: ISubtags): Result<ISubtags>;
+}
+
+/**
+ * @public
+ */
+export abstract class TagNormalizerBase {
+  protected readonly _iana: Iana.LanguageRegistries;
+
+  public abstract readonly normalization: TagNormalization;
+
+  public constructor(iana?: Iana.LanguageRegistries) {
+    /* c8 ignore next - dependency injection primarily for test */
+    this._iana = iana ?? Iana.DefaultRegistries.languageRegistries;
+  }
+
+  public processSubtags(subtags: ISubtags): Result<ISubtags> {
+    return populateObject<ISubtags>(
+      {
+        primaryLanguage: () => this._processLanguage(subtags),
+        extlangs: () => this._processExtlangs(subtags),
+        script: () => this._processScript(subtags),
+        region: () => this._processRegion(subtags),
+        variants: () => this._processVariants(subtags),
+        extensions: () => this._processExtensions(subtags),
+        privateUse: () => this._processPrivateUseTags(subtags),
+        grandfathered: () => this._processGrandfatheredTags(subtags)
+      },
+      { suppressUndefined: true }
+    ).onSuccess((processed) => {
+      return this._postValidate(processed);
+    });
+  }
+
+  protected _basicPostValidation(subtags: ISubtags): Result<ISubtags> {
+    /* c8 ignore next 7 - any validation whatsoever catches these so should never happen in practice */
+    if (
+      subtags.primaryLanguage === undefined &&
+      subtags.grandfathered === undefined &&
+      subtags.privateUse === undefined
+    ) {
+      return fail(`${subtagsToString(subtags)}: missing primary language subtag.`);
+    }
+
+    /* c8 ignore next 3 - any validation whatsoever catches these so should never happen in practice */
+    if (subtags.extlangs && subtags.extlangs.length > 3) {
+      return fail(`${subtagsToString(subtags)}: too many extlang subtags`);
+    }
+    return succeed(subtags);
+  }
+
+  protected _postValidate(subtags: ISubtags): Result<ISubtags> {
+    return this._basicPostValidation(subtags);
+  }
+
+  protected _processExtensions(subtags: ISubtags): Result<IExtensionSubtagValue[] | undefined> {
+    if (subtags.extensions) {
+      return mapResults(
+        subtags.extensions.map((ex) => {
+          return populateObject<IExtensionSubtagValue>({
+            singleton: () => this._processExtensionSingleton(ex.singleton),
+            value: () => this._processExtensionSubtagValue(ex.value)
+          });
+        })
+      );
+    }
+    return succeed(subtags.extensions);
+  }
+
+  protected _verifyUnique<T, TK extends string>(
+    description: string,
+    items: T[] | undefined,
+    getKey: (item: T) => TK
+  ): Result<T[] | undefined> {
+    if (items) {
+      const present = new Set<TK>();
+      return allSucceed(
+        items.map((i) => {
+          const key = getKey(i);
+          if (present.has(key)) {
+            return fail(`${key}: duplicate ${description}`);
+          }
+          present.add(key);
+          return succeed(key);
+        }),
+        items
+      );
+    }
+    return succeed(items);
+  }
+
+  protected abstract _processLanguage(
+    subtags: ISubtags
+  ): Result<Iana.LanguageSubtags.LanguageSubtag | undefined>;
+  protected abstract _processExtlangs(
+    subtags: ISubtags
+  ): Result<Iana.LanguageSubtags.ExtLangSubtag[] | undefined>;
+  protected abstract _processScript(subtags: ISubtags): Result<Iana.LanguageSubtags.ScriptSubtag | undefined>;
+  protected abstract _processRegion(subtags: ISubtags): Result<Iana.LanguageSubtags.RegionSubtag | undefined>;
+  protected abstract _processVariants(
+    subtags: ISubtags
+  ): Result<Iana.LanguageSubtags.VariantSubtag[] | undefined>;
+  protected abstract _processExtensionSingleton(singleton: ExtensionSingleton): Result<ExtensionSingleton>;
+  protected abstract _processExtensionSubtagValue(value: ExtensionSubtag): Result<ExtensionSubtag>;
+  protected abstract _processPrivateUseTags(
+    subtags: ISubtags
+  ): Result<Iana.LanguageSubtags.ExtendedLanguageRange[] | undefined>;
+  protected abstract _processGrandfatheredTags(
+    subtags: ISubtags
+  ): Result<Iana.LanguageSubtags.GrandfatheredTag | undefined>;
+}

package/src/packlets/bcp47/normalization/canonicalNormalizer.ts

@@ -0,0 +1,102 @@
+/*
+ * Copyright (c) 2022 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 Iana from '../../iana';
+import * as Bcp47Subtags from '../bcp47Subtags';
+
+import { Result, mapResults, succeed } from '@fgv/ts-utils';
+
+import { ExtensionSingleton, ExtensionSubtag } from '../bcp47Subtags/model';
+import { ISubtags } from '../common';
+import { TagNormalizerBase } from './baseNormalizer';
+import { TagNormalization } from './common';
+
+/**
+ * @internal
+ */
+export class CanonicalNormalizer extends TagNormalizerBase {
+  public readonly normalization: TagNormalization = 'canonical';
+
+  protected _processLanguage(subtags: ISubtags): Result<Iana.LanguageSubtags.LanguageSubtag | undefined> {
+    if (subtags.primaryLanguage) {
+      return this._iana.subtags.languages.toCanonical(subtags.primaryLanguage);
+    }
+    return succeed(subtags.primaryLanguage);
+  }
+
+  protected _processExtlangs(subtags: ISubtags): Result<Iana.LanguageSubtags.ExtLangSubtag[] | undefined> {
+    if (subtags.extlangs) {
+      return mapResults(subtags.extlangs.map((e) => this._iana.subtags.extlangs.toCanonical(e)));
+    }
+    return succeed(undefined);
+  }
+
+  protected _processScript(subtags: ISubtags): Result<Iana.LanguageSubtags.ScriptSubtag | undefined> {
+    if (subtags.script) {
+      return this._iana.subtags.scripts.toCanonical(subtags.script);
+    }
+    return succeed(undefined);
+  }
+
+  protected _processRegion(subtags: ISubtags): Result<Iana.LanguageSubtags.RegionSubtag | undefined> {
+    if (subtags.region) {
+      return this._iana.subtags.regions.toCanonical(subtags.region);
+    }
+    return succeed(undefined);
+  }
+
+  protected _processVariants(subtags: ISubtags): Result<Iana.LanguageSubtags.VariantSubtag[] | undefined> {
+    if (subtags.variants) {
+      return mapResults(subtags.variants.map((v) => this._iana.subtags.variants.toCanonical(v)));
+    }
+    return succeed(undefined);
+  }
+
+  protected _processExtensionSingleton(singleton: ExtensionSingleton): Result<ExtensionSingleton> {
+    return this._iana.extensions.extensions.toCanonical(singleton);
+  }
+
+  protected _processExtensionSubtagValue(value: ExtensionSubtag): Result<ExtensionSubtag> {
+    return Bcp47Subtags.Validate.extensionSubtag.toCanonical(value);
+  }
+
+  protected _processPrivateUseTags(
+    subtags: ISubtags
+  ): Result<Iana.LanguageSubtags.ExtendedLanguageRange[] | undefined> {
+    if (subtags.privateUse) {
+      const merged = subtags.privateUse.join('-');
+      return Iana.LanguageSubtags.Validate.extendedLanguageRange.toCanonical(merged).onSuccess((canon) => {
+        return succeed(canon.split('-') as Iana.LanguageSubtags.ExtendedLanguageRange[]);
+      });
+    }
+    return succeed(subtags.privateUse);
+  }
+
+  protected _processGrandfatheredTags(
+    subtags: ISubtags
+  ): Result<Iana.LanguageSubtags.GrandfatheredTag | undefined> {
+    if (subtags.grandfathered) {
+      return this._iana.subtags.grandfathered.toCanonical(subtags.grandfathered);
+    }
+    return succeed(undefined);
+  }
+}

package/src/packlets/bcp47/normalization/common.ts

@@ -0,0 +1,84 @@
+/*
+ * Copyright (c) 2022 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.
+ */
+
+/**
+ * Describes the degree of normalization of a language tag.
+ * @public
+ */
+export type TagNormalization = 'unknown' | 'none' | 'canonical' | 'preferred';
+
+/**
+ * Ordered ranking of the degrees of normalization, from `unknown` (least
+ * normalized) to `preferred` (most normalized).
+ * @public
+ */
+const normalizationRank: Record<TagNormalization, number> = {
+  /**
+   * Normalization level is unknown.
+   */
+  unknown: 0,
+  /**
+   * Not normalized.
+   */
+  none: 0.1,
+  /**
+   * Tag and subtag case has been normalized to canonical
+   * letter case (e.g. lower-case language and upper-case
+   * region) but no other normalization has been applied.
+   */
+  canonical: 0.9,
+  /**
+   * All tag recommendations have been applied - e.g. suppressed
+   * script is removed, deprecated or grandfathered values are
+   * replaced with preferred values.
+   */
+  preferred: 1.0
+};
+
+/**
+ * Determines which of two normalization ranks is most normalized.
+ * @param n1 - The first {@link TagNormalization} to be compared.
+ * @param n2 - The second {@link TagNormalization} to me compared.
+ * @returns `1` if `n1` is more normalized, `-1` if `n2` is more
+ * normalized, or `0` if they are identical.
+ * @public
+ */
+export function compareNormalization(n1: TagNormalization, n2: TagNormalization): -1 | 0 | 1 {
+  if (normalizationRank[n1] > normalizationRank[n2]) {
+    return 1;
+  } else if (normalizationRank[n1] < normalizationRank[n2]) {
+    return -1;
+  }
+  return 0;
+}
+
+/**
+ * Chooses the most normalized of two normalization ranks.
+ * @param n1 - The first {@link TagNormalization} to be compared.
+ * @param n2 - The second {@link TagNormalization} to me compared.
+ * @returns The most normalized of `n1` or `n2`.
+ * @public
+ */
+export function mostNormalized(n1: TagNormalization, n2: TagNormalization): TagNormalization {
+  /* c8 ignore next - hard to hit due to guards */
+  return normalizationRank[n1] > normalizationRank[n2] ? n1 : n2;
+}

package/src/packlets/bcp47/normalization/index.ts

@@ -0,0 +1,27 @@
+/*
+ * Copyright (c) 2022 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.
+ */
+// istanbul ignore file
+
+export * from './common';
+export { NormalizeTag } from './normalizeTag';
+export { CanonicalNormalizer } from './canonicalNormalizer';
+export { PreferredNormalizer } from './preferredTagNormalizer';