@twin.org/standards-unece 0.0.3-next.4 → 0.0.3-next.41

package/dist/es/helpers/unCodeLists.js

@@ -0,0 +1,153 @@
+// Copyright 2026 IOTA Stiftung.
+// SPDX-License-Identifier: Apache-2.0.
+import { GeneralError, Guards, I18n, Is, StringHelper } from "@twin.org/core";
+/**
+ * A class for handling Code Lists.
+ * @see https://vocabulary.uncefact.org/code-lists
+ */
+export class UnCodeLists {
+    /**
+     * The class name.
+     * @internal
+     */
+    static CLASS_NAME = "UnCodeLists";
+    /**
+     * Static cache for code list translations per locale.
+     * Key format: `${locale}:${camelCaseCodeListName}`
+     * @internal
+     */
+    static _cache = {};
+    /**
+     * Static cache for code list labels per locale.
+     * Key format: `${locale}:${camelCaseCodeListName}:labels`
+     * @internal
+     */
+    static _labelsCache = {};
+    /**
+     * Get all the translations for a specific list type.
+     * @param codeList The code list to get the translations for.
+     * @param locale The locale to get the translations for. If not provided, the default locale will be used. Falls back to 'en' if the locale doesn't exist.
+     * @returns The translations for the code list.
+     */
+    static async getDescriptions(codeList, locale) {
+        Guards.stringValue(UnCodeLists.CLASS_NAME, "codeList", codeList);
+        const parts = codeList.split(":");
+        if (parts.length !== 2 || parts[0] !== "unece") {
+            throw new GeneralError(UnCodeLists.CLASS_NAME, "invalidCodeList", { codeList });
+        }
+        const finalLocale = locale ?? I18n.getLocale();
+        const camelCaseCodeList = StringHelper.camelCase(parts[1]);
+        const cacheKey = `${finalLocale}:${camelCaseCodeList}`;
+        // Check if this code list is already cached
+        if (cacheKey in UnCodeLists._cache) {
+            return UnCodeLists._cache[cacheKey];
+        }
+        let dictionary = I18n.getDictionary(finalLocale);
+        let actualLocale = finalLocale;
+        const codeListPrefix = `codeLists.${camelCaseCodeList}.`;
+        // If the requested locale is empty or doesn't have translations for this code list, fall back to 'en'
+        let hasTranslations = false;
+        for (const key in dictionary) {
+            if (key.startsWith(codeListPrefix)) {
+                hasTranslations = true;
+                break;
+            }
+        }
+        if (!hasTranslations && finalLocale !== "en") {
+            dictionary = I18n.getDictionary("en");
+            actualLocale = "en";
+        }
+        const translations = {};
+        for (const key in dictionary) {
+            if (key.startsWith(codeListPrefix) && !key.endsWith("_label")) {
+                const codeKey = key.slice(codeListPrefix.length);
+                translations[codeKey] = dictionary[key];
+            }
+        }
+        // Cache under the actual locale used (accounting for fallback)
+        const actualCacheKey = `${actualLocale}:${camelCaseCodeList}`;
+        UnCodeLists._cache[actualCacheKey] = translations;
+        // Also cache under requested locale if it differs from actual locale (for faster fallback next time)
+        if (actualLocale !== finalLocale) {
+            UnCodeLists._cache[cacheKey] = translations;
+        }
+        return translations;
+    }
+    /**
+     * Get a translation for a specific list type.
+     * @param codeList The code list to get the translations for.
+     * @param key The key to get the translation for.
+     * @param locale The locale to get the translations for. If not provided, the default locale will be used.
+     * @returns The translation for the specified key in the code list.
+     */
+    static async getDescription(codeList, key, locale) {
+        const descriptions = await UnCodeLists.getDescriptions(codeList, locale);
+        if (Is.object(descriptions) && Is.string(descriptions[key])) {
+            return descriptions[key];
+        }
+        return undefined;
+    }
+    /**
+     * Get all the short description labels for a specific list type.
+     * Labels are stored in locale files with a `_label` suffix (e.g. `unece:arrivalEvent_label`).
+     * @param codeList The code list to get the labels for.
+     * @param locale The locale to get the labels for. If not provided, the default locale will be used. Falls back to 'en' if the locale doesn't exist.
+     * @returns The labels for the code list, keyed by the original code (without `_label` suffix).
+     */
+    static async getLabels(codeList, locale) {
+        Guards.stringValue(UnCodeLists.CLASS_NAME, "codeList", codeList);
+        const parts = codeList.split(":");
+        if (parts.length !== 2 || parts[0] !== "unece") {
+            throw new GeneralError(UnCodeLists.CLASS_NAME, "invalidCodeList", { codeList });
+        }
+        const finalLocale = locale ?? I18n.getLocale();
+        const camelCaseCodeList = StringHelper.camelCase(parts[1]);
+        const cacheKey = `${finalLocale}:${camelCaseCodeList}:labels`;
+        if (cacheKey in UnCodeLists._labelsCache) {
+            return UnCodeLists._labelsCache[cacheKey];
+        }
+        let dictionary = I18n.getDictionary(finalLocale);
+        let actualLocale = finalLocale;
+        const labelSuffix = "_label";
+        const codeListPrefix = `codeLists.${camelCaseCodeList}.`;
+        let hasTranslations = false;
+        for (const key in dictionary) {
+            if (key.startsWith(codeListPrefix) && key.endsWith(labelSuffix)) {
+                hasTranslations = true;
+                break;
+            }
+        }
+        if (!hasTranslations && finalLocale !== "en") {
+            dictionary = I18n.getDictionary("en");
+            actualLocale = "en";
+        }
+        const labels = {};
+        for (const key in dictionary) {
+            if (key.startsWith(codeListPrefix) && key.endsWith(labelSuffix)) {
+                const codeKey = key.slice(codeListPrefix.length, -labelSuffix.length);
+                labels[codeKey] = dictionary[key];
+            }
+        }
+        const actualCacheKey = `${actualLocale}:${camelCaseCodeList}:labels`;
+        UnCodeLists._labelsCache[actualCacheKey] = labels;
+        if (actualLocale !== finalLocale) {
+            UnCodeLists._labelsCache[cacheKey] = labels;
+        }
+        return labels;
+    }
+    /**
+     * Get a short description label for a specific code in a list type.
+     * @param codeList The code list to get the label for.
+     * @param key The key to get the label for.
+     * @param locale The locale to get the label for. If not provided, the default locale will be used.
+     * @returns The label for the specified key in the code list.
+     */
+    static async getLabel(codeList, key, locale) {
+        const labels = await UnCodeLists.getLabels(codeList, locale);
+        if (Is.object(labels) && Is.string(labels[key])) {
+            return labels[key];
+        }
+        return undefined;
+    }
+}
+//# sourceMappingURL=unCodeLists.js.map

package/dist/es/helpers/unCodeLists.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"unCodeLists.js","sourceRoot":"","sources":["../../../src/helpers/unCodeLists.ts"],"names":[],"mappings":"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","sourcesContent":["// Copyright 2026 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport { GeneralError, Guards, I18n, Is, StringHelper } from \"@twin.org/core\";\nimport { nameof } from \"@twin.org/nameof\";\nimport type { UneceCodeLists } from \"../models/uneceCodeLists.js\";\n\n/**\n * A class for handling Code Lists.\n * @see https://vocabulary.uncefact.org/code-lists\n */\nexport class UnCodeLists {\n\t/**\n\t * The class name.\n\t * @internal\n\t */\n\tpublic static readonly CLASS_NAME = nameof<UnCodeLists>();\n\n\t/**\n\t * Static cache for code list translations per locale.\n\t * Key format: `${locale}:${camelCaseCodeListName}`\n\t * @internal\n\t */\n\tprivate static readonly _cache: { [key: string]: { [key: string]: string } } = {};\n\n\t/**\n\t * Static cache for code list labels per locale.\n\t * Key format: `${locale}:${camelCaseCodeListName}:labels`\n\t * @internal\n\t */\n\tprivate static readonly _labelsCache: { [key: string]: { [key: string]: string } } = {};\n\n\t/**\n\t * Get all the translations for a specific list type.\n\t * @param codeList The code list to get the translations for.\n\t * @param locale The locale to get the translations for. If not provided, the default locale will be used. Falls back to 'en' if the locale doesn't exist.\n\t * @returns The translations for the code list.\n\t */\n\tpublic static async getDescriptions(\n\t\tcodeList: UneceCodeLists,\n\t\tlocale?: string\n\t): Promise<{\n\t\t[key: string]: string;\n\t}> {\n\t\tGuards.stringValue(UnCodeLists.CLASS_NAME, nameof(codeList), codeList);\n\n\t\tconst parts = codeList.split(\":\");\n\t\tif (parts.length !== 2 || parts[0] !== \"unece\") {\n\t\t\tthrow new GeneralError(UnCodeLists.CLASS_NAME, \"invalidCodeList\", { codeList });\n\t\t}\n\n\t\tconst finalLocale = locale ?? I18n.getLocale();\n\t\tconst camelCaseCodeList = StringHelper.camelCase(parts[1]);\n\t\tconst cacheKey = `${finalLocale}:${camelCaseCodeList}`;\n\n\t\t// Check if this code list is already cached\n\t\tif (cacheKey in UnCodeLists._cache) {\n\t\t\treturn UnCodeLists._cache[cacheKey];\n\t\t}\n\n\t\tlet dictionary = I18n.getDictionary(finalLocale);\n\t\tlet actualLocale = finalLocale;\n\t\tconst codeListPrefix = `codeLists.${camelCaseCodeList}.`;\n\n\t\t// If the requested locale is empty or doesn't have translations for this code list, fall back to 'en'\n\t\tlet hasTranslations = false;\n\t\tfor (const key in dictionary) {\n\t\t\tif (key.startsWith(codeListPrefix)) {\n\t\t\t\thasTranslations = true;\n\t\t\t\tbreak;\n\t\t\t}\n\t\t}\n\n\t\tif (!hasTranslations && finalLocale !== \"en\") {\n\t\t\tdictionary = I18n.getDictionary(\"en\");\n\t\t\tactualLocale = \"en\";\n\t\t}\n\n\t\tconst translations: { [key: string]: string } = {};\n\t\tfor (const key in dictionary) {\n\t\t\tif (key.startsWith(codeListPrefix) && !key.endsWith(\"_label\")) {\n\t\t\t\tconst codeKey = key.slice(codeListPrefix.length);\n\t\t\t\ttranslations[codeKey] = dictionary[key];\n\t\t\t}\n\t\t}\n\n\t\t// Cache under the actual locale used (accounting for fallback)\n\t\tconst actualCacheKey = `${actualLocale}:${camelCaseCodeList}`;\n\t\tUnCodeLists._cache[actualCacheKey] = translations;\n\n\t\t// Also cache under requested locale if it differs from actual locale (for faster fallback next time)\n\t\tif (actualLocale !== finalLocale) {\n\t\t\tUnCodeLists._cache[cacheKey] = translations;\n\t\t}\n\n\t\treturn translations;\n\t}\n\n\t/**\n\t * Get a translation for a specific list type.\n\t * @param codeList The code list to get the translations for.\n\t * @param key The key to get the translation for.\n\t * @param locale The locale to get the translations for. If not provided, the default locale will be used.\n\t * @returns The translation for the specified key in the code list.\n\t */\n\tpublic static async getDescription(\n\t\tcodeList: UneceCodeLists,\n\t\tkey: string,\n\t\tlocale?: string\n\t): Promise<string | undefined> {\n\t\tconst descriptions = await UnCodeLists.getDescriptions(codeList, locale);\n\n\t\tif (Is.object(descriptions) && Is.string(descriptions[key])) {\n\t\t\treturn descriptions[key];\n\t\t}\n\n\t\treturn undefined;\n\t}\n\n\t/**\n\t * Get all the short description labels for a specific list type.\n\t * Labels are stored in locale files with a `_label` suffix (e.g. `unece:arrivalEvent_label`).\n\t * @param codeList The code list to get the labels for.\n\t * @param locale The locale to get the labels for. If not provided, the default locale will be used. Falls back to 'en' if the locale doesn't exist.\n\t * @returns The labels for the code list, keyed by the original code (without `_label` suffix).\n\t */\n\tpublic static async getLabels(\n\t\tcodeList: UneceCodeLists,\n\t\tlocale?: string\n\t): Promise<{\n\t\t[key: string]: string;\n\t}> {\n\t\tGuards.stringValue(UnCodeLists.CLASS_NAME, nameof(codeList), codeList);\n\n\t\tconst parts = codeList.split(\":\");\n\t\tif (parts.length !== 2 || parts[0] !== \"unece\") {\n\t\t\tthrow new GeneralError(UnCodeLists.CLASS_NAME, \"invalidCodeList\", { codeList });\n\t\t}\n\n\t\tconst finalLocale = locale ?? I18n.getLocale();\n\t\tconst camelCaseCodeList = StringHelper.camelCase(parts[1]);\n\t\tconst cacheKey = `${finalLocale}:${camelCaseCodeList}:labels`;\n\n\t\tif (cacheKey in UnCodeLists._labelsCache) {\n\t\t\treturn UnCodeLists._labelsCache[cacheKey];\n\t\t}\n\n\t\tlet dictionary = I18n.getDictionary(finalLocale);\n\t\tlet actualLocale = finalLocale;\n\t\tconst labelSuffix = \"_label\";\n\t\tconst codeListPrefix = `codeLists.${camelCaseCodeList}.`;\n\n\t\tlet hasTranslations = false;\n\t\tfor (const key in dictionary) {\n\t\t\tif (key.startsWith(codeListPrefix) && key.endsWith(labelSuffix)) {\n\t\t\t\thasTranslations = true;\n\t\t\t\tbreak;\n\t\t\t}\n\t\t}\n\n\t\tif (!hasTranslations && finalLocale !== \"en\") {\n\t\t\tdictionary = I18n.getDictionary(\"en\");\n\t\t\tactualLocale = \"en\";\n\t\t}\n\n\t\tconst labels: { [key: string]: string } = {};\n\t\tfor (const key in dictionary) {\n\t\t\tif (key.startsWith(codeListPrefix) && key.endsWith(labelSuffix)) {\n\t\t\t\tconst codeKey = key.slice(codeListPrefix.length, -labelSuffix.length);\n\t\t\t\tlabels[codeKey] = dictionary[key];\n\t\t\t}\n\t\t}\n\n\t\tconst actualCacheKey = `${actualLocale}:${camelCaseCodeList}:labels`;\n\t\tUnCodeLists._labelsCache[actualCacheKey] = labels;\n\n\t\tif (actualLocale !== finalLocale) {\n\t\t\tUnCodeLists._labelsCache[cacheKey] = labels;\n\t\t}\n\n\t\treturn labels;\n\t}\n\n\t/**\n\t * Get a short description label for a specific code in a list type.\n\t * @param codeList The code list to get the label for.\n\t * @param key The key to get the label for.\n\t * @param locale The locale to get the label for. If not provided, the default locale will be used.\n\t * @returns The label for the specified key in the code list.\n\t */\n\tpublic static async getLabel(\n\t\tcodeList: UneceCodeLists,\n\t\tkey: string,\n\t\tlocale?: string\n\t): Promise<string | undefined> {\n\t\tconst labels = await UnCodeLists.getLabels(codeList, locale);\n\n\t\tif (Is.object(labels) && Is.string(labels[key])) {\n\t\t\treturn labels[key];\n\t\t}\n\n\t\treturn undefined;\n\t}\n}\n"]}

package/dist/es/helpers/unLocodes.js

@@ -0,0 +1,275 @@
+// Copyright 2026 IOTA Stiftung.
+// SPDX-License-Identifier: Apache-2.0.
+import fs from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { Compression, CompressionType, Guards, Is, ObjectHelper } from "@twin.org/core";
+import { UN_LOCODE_COUNTRIES } from "../models/locode/unLocodeCountries.js";
+import { UN_LOCODE_FUNCTIONS } from "../models/locode/unLocodeFunctions.js";
+/**
+ * A class handling UN/LOCODEs.
+ * @see https://vocabulary.uncefact.org/unlocode-about
+ */
+export class UnLocodes {
+    /**
+     * The class name.
+     * @internal
+     */
+    static CLASS_NAME = "UnLocodes";
+    /**
+     * The URI prefix for UN/LOCODE locations.
+     * @internal
+     */
+    static LOCODE_COUNTRY_URI_PREFIX = "unlcdc:";
+    /**
+     * The URI prefix for UN/LOCODE locations.
+     * @internal
+     */
+    static LOCODE_LOCATION_URI_PREFIX = "unlcd:";
+    /**
+     * The URI prefix for UN/LOCODE sub-divisions.
+     * @internal
+     */
+    static LOCODE_SUBDIVISION_URI_PREFIX = "unlcds:";
+    /**
+     * The URI prefix for UN/LOCODE functions.
+     * @internal
+     */
+    static LOCODE_FUNCTION_URI_PREFIX = "unlcdf:";
+    /**
+     * Cache for loaded locations by country code.
+     * @internal
+     */
+    static _locationsByCountry = {};
+    /**
+     * Cache for loaded subdivisions by country code.
+     * @internal
+     */
+    static _subdivisionsByCountry = {};
+    /**
+     * Get the list of UN/LOCODE countries.
+     * @see https://vocabulary.uncefact.org/unlocode-countries
+     * @returns The list of UN/LOCODE countries.
+     */
+    static async getCountries() {
+        return UN_LOCODE_COUNTRIES;
+    }
+    /**
+     * Get the country by its uri.
+     * @param countryUri The country URI.
+     * @see https://vocabulary.uncefact.org/unlocode-countries
+     * @returns The country information or undefined if not found.
+     */
+    static async getCountryByUri(countryUri) {
+        Guards.stringValue(UnLocodes.CLASS_NAME, "countryUri", countryUri);
+        return UN_LOCODE_COUNTRIES.find(country => country.uri === countryUri);
+    }
+    /**
+     * Get the country by its value.
+     * @param countryValue The country value.
+     * @see https://vocabulary.uncefact.org/unlocode-countries
+     * @returns The country information or undefined if not found.
+     */
+    static async getCountryByValue(countryValue) {
+        Guards.stringValue(UnLocodes.CLASS_NAME, "countryValue", countryValue);
+        return UN_LOCODE_COUNTRIES.find(country => country.value === countryValue);
+    }
+    /**
+     * Get the list of UN/LOCODE functions.
+     * @see https://vocabulary.uncefact.org/unlocode-functions
+     * @returns The list of UN/LOCODE functions.
+     */
+    static async getFunctions() {
+        return UN_LOCODE_FUNCTIONS;
+    }
+    /**
+     * Get the function by its uri.
+     * @param functionUri The function URI.
+     * @see https://vocabulary.uncefact.org/unlocode-functions
+     * @returns The function information or undefined if not found.
+     */
+    static async getFunctionByUri(functionUri) {
+        Guards.stringValue(UnLocodes.CLASS_NAME, "functionUri", functionUri);
+        return UN_LOCODE_FUNCTIONS.find(func => func.uri === functionUri);
+    }
+    /**
+     * Get the function by its value.
+     * @param functionValue The function value.
+     * @see https://vocabulary.uncefact.org/unlocode-functions
+     * @returns The function information or undefined if not found.
+     */
+    static async getFunctionByValue(functionValue) {
+        Guards.stringValue(UnLocodes.CLASS_NAME, "functionValue", functionValue);
+        return UN_LOCODE_FUNCTIONS.find(func => func.value === functionValue);
+    }
+    /**
+     * Get the location by its UN/LOCODE.
+     * @param unLocode The UN/LOCODE value.
+     * @see https://vocabulary.uncefact.org/unlocode-about
+     * @returns The location information or undefined if not found.
+     */
+    static async getLocationByCode(unLocode) {
+        Guards.stringValue(UnLocodes.CLASS_NAME, "unLocode", unLocode);
+        const countryCode = unLocode.slice(0, 2);
+        const locationCode = unLocode.slice(2);
+        if (!Is.stringValue(countryCode) || !Is.stringValue(locationCode)) {
+            return undefined;
+        }
+        const locations = await UnLocodes.getLocations(countryCode);
+        return locations.find(location => location.locode === unLocode);
+    }
+    /**
+     * Get the location by its UN/LOCODE uri.
+     * @param unLocodeUri The UN/LOCODE URI.
+     * @see https://vocabulary.uncefact.org/unlocode-about
+     * @returns The location information or undefined if not found.
+     */
+    static async getLocationByUri(unLocodeUri) {
+        Guards.stringValue(UnLocodes.CLASS_NAME, "unLocodeUri", unLocodeUri);
+        const normalized = unLocodeUri.replace(UnLocodes.LOCODE_LOCATION_URI_PREFIX, "").trim();
+        return UnLocodes.getLocationByCode(normalized);
+    }
+    /**
+     * Get the location by its label.
+     * @param label The location label.
+     * @see https://vocabulary.uncefact.org/unlocode-about
+     * @returns The location information or undefined if not found.
+     */
+    static async getLocationByLabel(label) {
+        Guards.stringValue(UnLocodes.CLASS_NAME, "label", label);
+        const normalized = label.trim().toLowerCase();
+        for (const country of UN_LOCODE_COUNTRIES) {
+            const locations = await UnLocodes.getLocations(country.value);
+            const match = locations.find(location => location.label.toLowerCase() === normalized ||
+                location.labelWithDiacritics.toLowerCase() === normalized);
+            if (match) {
+                return match;
+            }
+        }
+        return undefined;
+    }
+    /**
+     * Get the subdivision by its code.
+     * @param subdivisionCode The subdivision code (e.g., "AD04").
+     * @returns The subdivision information or undefined if not found.
+     */
+    static async getSubdivisionByCode(subdivisionCode) {
+        Guards.stringValue(UnLocodes.CLASS_NAME, "subdivisionCode", subdivisionCode);
+        const countryCode = subdivisionCode.slice(0, 2);
+        const code = subdivisionCode.slice(2);
+        if (!Is.stringValue(countryCode) || !Is.stringValue(code)) {
+            return undefined;
+        }
+        const subdivisions = await UnLocodes.getSubdivisions(countryCode);
+        return subdivisions.find(subdivision => subdivision.code === code);
+    }
+    /**
+     * Get the subdivision by its URI.
+     * @param subdivisionUri The subdivision URI (e.g., "unlcds:AD04").
+     * @returns The subdivision information or undefined if not found.
+     */
+    static async getSubdivisionByUri(subdivisionUri) {
+        Guards.stringValue(UnLocodes.CLASS_NAME, "subdivisionUri", subdivisionUri);
+        const normalized = subdivisionUri.replace(UnLocodes.LOCODE_SUBDIVISION_URI_PREFIX, "").trim();
+        return UnLocodes.getSubdivisionByCode(normalized);
+    }
+    /**
+     * Get the locations for a given country code.
+     * @param countryCode The country code.
+     * @returns The list of locations for the country.
+     * @throws Error if the country code is invalid or if the data file cannot be loaded.
+     */
+    static async getLocations(countryCode) {
+        return UnLocodes.loadCompressedFile("countries", countryCode, (normalized, record) => UnLocodes.mapCountryLocation(normalized, record), UnLocodes._locationsByCountry);
+    }
+    /**
+     * Get the subdivisions for a given country code.
+     * @param countryCode The country code.
+     * @returns The list of subdivisions for the country.
+     * @throws Error if the country code is invalid or if the data file cannot be loaded.
+     */
+    static async getSubdivisions(countryCode) {
+        return UnLocodes.loadCompressedFile("subdivisions", countryCode, (normalized, record) => UnLocodes.mapCountrySubdivision(normalized, record), UnLocodes._subdivisionsByCountry);
+    }
+    /**
+     * Map a country location record to a location object.
+     * @param countryCode	The country code.
+     * @param record The country location record.
+     * @returns The mapped location object.
+     * @internal
+     */
+    static mapCountryLocation(countryCode, record) {
+        const locode = `${countryCode}${record.locationCode}`;
+        const countryCodeUri = UN_LOCODE_COUNTRIES.find(country => country.value === countryCode)?.uri;
+        const countrySubdivisionUri = Is.stringValue(record.subdivisionCode)
+            ? `${UnLocodes.LOCODE_SUBDIVISION_URI_PREFIX}${countryCode}${record.subdivisionCode}`
+            : "";
+        const functions = record.function
+            ? record.function.split("").map(code => `${UnLocodes.LOCODE_FUNCTION_URI_PREFIX}${code}`)
+            : [];
+        const location = {
+            locode,
+            locodeUri: `${UnLocodes.LOCODE_LOCATION_URI_PREFIX}${locode}`,
+            label: record.label,
+            // If the label with diacritics is not provided, use the regular label as fallback
+            // as we don't store them if they are the same
+            labelWithDiacritics: record.labelWithDiacritics ?? record.label,
+            countryCodeUri: countryCodeUri,
+            countrySubdivisionUri,
+            functions: functions
+        };
+        if (Is.number(record.lat) && Is.number(record.lng)) {
+            location.geoCoordinates = {
+                latitude: record.lat,
+                longitude: record.lng
+            };
+        }
+        return location;
+    }
+    /**
+     * Map a country subdivision record to a subdivision object.
+     * @param countryCode The country code.
+     * @param record The country subdivision record.
+     * @returns The mapped subdivision object.
+     * @internal
+     */
+    static mapCountrySubdivision(countryCode, record) {
+        const countryCodeUri = UN_LOCODE_COUNTRIES.find(country => country.value === countryCode)?.uri;
+        const subdivision = {
+            code: record.code,
+            subdivisionUri: `${UnLocodes.LOCODE_SUBDIVISION_URI_PREFIX}${countryCode}${record.code}`,
+            label: record.label,
+            countryCodeUri,
+            type: record.type
+        };
+        return subdivision;
+    }
+    /**
+     * Load a compressed file.
+     * @param folder The folder to load (e.g., "countries" or "subdivisions").
+     * @param countryCode The country code.
+     * @return The loaded data as an array of records.
+     * @throws Error if the file cannot be loaded or decompressed.
+     * @internal
+     */
+    static async loadCompressedFile(folder, countryCode, mapMethod, cache) {
+        Guards.stringValue(UnLocodes.CLASS_NAME, "countryCode", countryCode);
+        const normalized = countryCode.replace(UnLocodes.LOCODE_COUNTRY_URI_PREFIX, "").toUpperCase();
+        const cached = cache[normalized];
+        if (cached) {
+            return cached;
+        }
+        try {
+            const thisFilename = fileURLToPath(import.meta.url);
+            const thisDirname = path.dirname(thisFilename);
+            const filePath = path.join(thisDirname, `../data/${folder}/`, `${normalized}.json.gz`);
+            const compressed = await fs.readFile(filePath);
+            const jsonBuffer = await Compression.decompress(compressed, CompressionType.Gzip);
+            const records = ObjectHelper.fromBytes(jsonBuffer);
+            cache[normalized] = records.map(record => mapMethod(normalized, record));
+        }
+        catch { }
+        return cache[normalized] ?? [];
+    }
+}
+//# sourceMappingURL=unLocodes.js.map

package/dist/es/helpers/unLocodes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"unLocodes.js","sourceRoot":"","sources":["../../../src/helpers/unLocodes.ts"],"names":[],"mappings":"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","sourcesContent":["// Copyright 2026 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport fs from \"node:fs/promises\";\nimport path from \"node:path\";\nimport { fileURLToPath } from \"node:url\";\nimport { Compression, CompressionType, Guards, Is, ObjectHelper } from \"@twin.org/core\";\nimport { nameof } from \"@twin.org/nameof\";\nimport type { IUnLocodeCountry } from \"../models/IUnLocodeCountry.js\";\nimport type { IUnLocodeCountrySubdivisionRecord } from \"../models/IUnLocodeCountrySubdivisionRecord.js\";\nimport type { IUnLocodeFunction } from \"../models/IUnLocodeFunction.js\";\nimport type { IUnLocodeLocation } from \"../models/IUnLocodeLocation.js\";\nimport type { IUnLocodeLocationRecord } from \"../models/IUnLocodeLocationRecord.js\";\nimport type { IUnLocodeSubdivision } from \"../models/IUnLocodeSubdivision.js\";\nimport { UN_LOCODE_COUNTRIES } from \"../models/locode/unLocodeCountries.js\";\nimport type { UnLocodeCountriesList } from \"../models/locode/unLocodeCountriesList.js\";\nimport { UN_LOCODE_FUNCTIONS } from \"../models/locode/unLocodeFunctions.js\";\nimport type { UnLocodeFunctionsList } from \"../models/locode/unLocodeFunctionsList.js\";\n\n/**\n * A class handling UN/LOCODEs.\n * @see https://vocabulary.uncefact.org/unlocode-about\n */\nexport class UnLocodes {\n\t/**\n\t * The class name.\n\t * @internal\n\t */\n\tpublic static readonly CLASS_NAME = nameof<UnLocodes>();\n\n\t/**\n\t * The URI prefix for UN/LOCODE locations.\n\t * @internal\n\t */\n\tpublic static readonly LOCODE_COUNTRY_URI_PREFIX = \"unlcdc:\";\n\n\t/**\n\t * The URI prefix for UN/LOCODE locations.\n\t * @internal\n\t */\n\tpublic static readonly LOCODE_LOCATION_URI_PREFIX = \"unlcd:\";\n\n\t/**\n\t * The URI prefix for UN/LOCODE sub-divisions.\n\t * @internal\n\t */\n\tpublic static readonly LOCODE_SUBDIVISION_URI_PREFIX = \"unlcds:\";\n\n\t/**\n\t * The URI prefix for UN/LOCODE functions.\n\t * @internal\n\t */\n\tpublic static readonly LOCODE_FUNCTION_URI_PREFIX = \"unlcdf:\";\n\n\t/**\n\t * Cache for loaded locations by country code.\n\t * @internal\n\t */\n\tprivate static readonly _locationsByCountry: { [country: string]: IUnLocodeLocation[] } = {};\n\n\t/**\n\t * Cache for loaded subdivisions by country code.\n\t * @internal\n\t */\n\tprivate static readonly _subdivisionsByCountry: { [country: string]: IUnLocodeSubdivision[] } =\n\t\t{};\n\n\t/**\n\t * Get the list of UN/LOCODE countries.\n\t * @see https://vocabulary.uncefact.org/unlocode-countries\n\t * @returns The list of UN/LOCODE countries.\n\t */\n\tpublic static async getCountries(): Promise<IUnLocodeCountry[]> {\n\t\treturn UN_LOCODE_COUNTRIES;\n\t}\n\n\t/**\n\t * Get the country by its uri.\n\t * @param countryUri The country URI.\n\t * @see https://vocabulary.uncefact.org/unlocode-countries\n\t * @returns The country information or undefined if not found.\n\t */\n\tpublic static async getCountryByUri(countryUri: string): Promise<IUnLocodeCountry | undefined> {\n\t\tGuards.stringValue(UnLocodes.CLASS_NAME, nameof(countryUri), countryUri);\n\n\t\treturn UN_LOCODE_COUNTRIES.find(country => country.uri === countryUri);\n\t}\n\n\t/**\n\t * Get the country by its value.\n\t * @param countryValue The country value.\n\t * @see https://vocabulary.uncefact.org/unlocode-countries\n\t * @returns The country information or undefined if not found.\n\t */\n\tpublic static async getCountryByValue(\n\t\tcountryValue: string\n\t): Promise<IUnLocodeCountry | undefined> {\n\t\tGuards.stringValue(UnLocodes.CLASS_NAME, nameof(countryValue), countryValue);\n\n\t\treturn UN_LOCODE_COUNTRIES.find(country => country.value === countryValue);\n\t}\n\n\t/**\n\t * Get the list of UN/LOCODE functions.\n\t * @see https://vocabulary.uncefact.org/unlocode-functions\n\t * @returns The list of UN/LOCODE functions.\n\t */\n\tpublic static async getFunctions(): Promise<IUnLocodeFunction[]> {\n\t\treturn UN_LOCODE_FUNCTIONS;\n\t}\n\n\t/**\n\t * Get the function by its uri.\n\t * @param functionUri The function URI.\n\t * @see https://vocabulary.uncefact.org/unlocode-functions\n\t * @returns The function information or undefined if not found.\n\t */\n\tpublic static async getFunctionByUri(\n\t\tfunctionUri: string\n\t): Promise<IUnLocodeFunction | undefined> {\n\t\tGuards.stringValue(UnLocodes.CLASS_NAME, nameof(functionUri), functionUri);\n\n\t\treturn UN_LOCODE_FUNCTIONS.find(func => func.uri === functionUri);\n\t}\n\n\t/**\n\t * Get the function by its value.\n\t * @param functionValue The function value.\n\t * @see https://vocabulary.uncefact.org/unlocode-functions\n\t * @returns The function information or undefined if not found.\n\t */\n\tpublic static async getFunctionByValue(\n\t\tfunctionValue: string\n\t): Promise<IUnLocodeFunction | undefined> {\n\t\tGuards.stringValue(UnLocodes.CLASS_NAME, nameof(functionValue), functionValue);\n\n\t\treturn UN_LOCODE_FUNCTIONS.find(func => func.value === functionValue);\n\t}\n\n\t/**\n\t * Get the location by its UN/LOCODE.\n\t * @param unLocode The UN/LOCODE value.\n\t * @see https://vocabulary.uncefact.org/unlocode-about\n\t * @returns The location information or undefined if not found.\n\t */\n\tpublic static async getLocationByCode(unLocode: string): Promise<IUnLocodeLocation | undefined> {\n\t\tGuards.stringValue(UnLocodes.CLASS_NAME, nameof(unLocode), unLocode);\n\n\t\tconst countryCode = unLocode.slice(0, 2);\n\t\tconst locationCode = unLocode.slice(2);\n\t\tif (!Is.stringValue(countryCode) || !Is.stringValue(locationCode)) {\n\t\t\treturn undefined;\n\t\t}\n\n\t\tconst locations = await UnLocodes.getLocations(countryCode);\n\t\treturn locations.find(location => location.locode === unLocode);\n\t}\n\n\t/**\n\t * Get the location by its UN/LOCODE uri.\n\t * @param unLocodeUri The UN/LOCODE URI.\n\t * @see https://vocabulary.uncefact.org/unlocode-about\n\t * @returns The location information or undefined if not found.\n\t */\n\tpublic static async getLocationByUri(\n\t\tunLocodeUri: string\n\t): Promise<IUnLocodeLocation | undefined> {\n\t\tGuards.stringValue(UnLocodes.CLASS_NAME, nameof(unLocodeUri), unLocodeUri);\n\n\t\tconst normalized = unLocodeUri.replace(UnLocodes.LOCODE_LOCATION_URI_PREFIX, \"\").trim();\n\n\t\treturn UnLocodes.getLocationByCode(normalized);\n\t}\n\n\t/**\n\t * Get the location by its label.\n\t * @param label The location label.\n\t * @see https://vocabulary.uncefact.org/unlocode-about\n\t * @returns The location information or undefined if not found.\n\t */\n\tpublic static async getLocationByLabel(label: string): Promise<IUnLocodeLocation | undefined> {\n\t\tGuards.stringValue(UnLocodes.CLASS_NAME, nameof(label), label);\n\n\t\tconst normalized = label.trim().toLowerCase();\n\t\tfor (const country of UN_LOCODE_COUNTRIES) {\n\t\t\tconst locations = await UnLocodes.getLocations(country.value);\n\t\t\tconst match = locations.find(\n\t\t\t\tlocation =>\n\t\t\t\t\tlocation.label.toLowerCase() === normalized ||\n\t\t\t\t\tlocation.labelWithDiacritics.toLowerCase() === normalized\n\t\t\t);\n\t\t\tif (match) {\n\t\t\t\treturn match;\n\t\t\t}\n\t\t}\n\n\t\treturn undefined;\n\t}\n\n\t/**\n\t * Get the subdivision by its code.\n\t * @param subdivisionCode The subdivision code (e.g., \"AD04\").\n\t * @returns The subdivision information or undefined if not found.\n\t */\n\tpublic static async getSubdivisionByCode(\n\t\tsubdivisionCode: string\n\t): Promise<IUnLocodeSubdivision | undefined> {\n\t\tGuards.stringValue(UnLocodes.CLASS_NAME, nameof(subdivisionCode), subdivisionCode);\n\n\t\tconst countryCode = subdivisionCode.slice(0, 2);\n\t\tconst code = subdivisionCode.slice(2);\n\t\tif (!Is.stringValue(countryCode) || !Is.stringValue(code)) {\n\t\t\treturn undefined;\n\t\t}\n\n\t\tconst subdivisions = await UnLocodes.getSubdivisions(countryCode);\n\t\treturn subdivisions.find(subdivision => subdivision.code === code);\n\t}\n\n\t/**\n\t * Get the subdivision by its URI.\n\t * @param subdivisionUri The subdivision URI (e.g., \"unlcds:AD04\").\n\t * @returns The subdivision information or undefined if not found.\n\t */\n\tpublic static async getSubdivisionByUri(\n\t\tsubdivisionUri: string\n\t): Promise<IUnLocodeSubdivision | undefined> {\n\t\tGuards.stringValue(UnLocodes.CLASS_NAME, nameof(subdivisionUri), subdivisionUri);\n\n\t\tconst normalized = subdivisionUri.replace(UnLocodes.LOCODE_SUBDIVISION_URI_PREFIX, \"\").trim();\n\n\t\treturn UnLocodes.getSubdivisionByCode(normalized);\n\t}\n\n\t/**\n\t * Get the locations for a given country code.\n\t * @param countryCode The country code.\n\t * @returns The list of locations for the country.\n\t * @throws Error if the country code is invalid or if the data file cannot be loaded.\n\t */\n\tpublic static async getLocations(countryCode: string): Promise<IUnLocodeLocation[]> {\n\t\treturn UnLocodes.loadCompressedFile<IUnLocodeLocationRecord, IUnLocodeLocation>(\n\t\t\t\"countries\",\n\t\t\tcountryCode,\n\t\t\t(normalized, record) => UnLocodes.mapCountryLocation(normalized, record),\n\t\t\tUnLocodes._locationsByCountry\n\t\t);\n\t}\n\n\t/**\n\t * Get the subdivisions for a given country code.\n\t * @param countryCode The country code.\n\t * @returns The list of subdivisions for the country.\n\t * @throws Error if the country code is invalid or if the data file cannot be loaded.\n\t */\n\tpublic static async getSubdivisions(countryCode: string): Promise<IUnLocodeSubdivision[]> {\n\t\treturn UnLocodes.loadCompressedFile<IUnLocodeCountrySubdivisionRecord, IUnLocodeSubdivision>(\n\t\t\t\"subdivisions\",\n\t\t\tcountryCode,\n\t\t\t(normalized, record) => UnLocodes.mapCountrySubdivision(normalized, record),\n\t\t\tUnLocodes._subdivisionsByCountry\n\t\t);\n\t}\n\n\t/**\n\t * Map a country location record to a location object.\n\t * @param countryCode\tThe country code.\n\t * @param record The country location record.\n\t * @returns The mapped location object.\n\t * @internal\n\t */\n\tprivate static mapCountryLocation(\n\t\tcountryCode: string,\n\t\trecord: IUnLocodeLocationRecord\n\t): IUnLocodeLocation {\n\t\tconst locode = `${countryCode}${record.locationCode}`;\n\t\tconst countryCodeUri = UN_LOCODE_COUNTRIES.find(country => country.value === countryCode)?.uri;\n\t\tconst countrySubdivisionUri = Is.stringValue(record.subdivisionCode)\n\t\t\t? `${UnLocodes.LOCODE_SUBDIVISION_URI_PREFIX}${countryCode}${record.subdivisionCode}`\n\t\t\t: \"\";\n\t\tconst functions = record.function\n\t\t\t? record.function.split(\"\").map(code => `${UnLocodes.LOCODE_FUNCTION_URI_PREFIX}${code}`)\n\t\t\t: [];\n\t\tconst location: IUnLocodeLocation = {\n\t\t\tlocode,\n\t\t\tlocodeUri: `${UnLocodes.LOCODE_LOCATION_URI_PREFIX}${locode}`,\n\t\t\tlabel: record.label,\n\t\t\t// If the label with diacritics is not provided, use the regular label as fallback\n\t\t\t// as we don't store them if they are the same\n\t\t\tlabelWithDiacritics: record.labelWithDiacritics ?? record.label,\n\t\t\tcountryCodeUri: countryCodeUri as UnLocodeCountriesList,\n\t\t\tcountrySubdivisionUri,\n\t\t\tfunctions: functions as UnLocodeFunctionsList[]\n\t\t};\n\t\tif (Is.number(record.lat) && Is.number(record.lng)) {\n\t\t\tlocation.geoCoordinates = {\n\t\t\t\tlatitude: record.lat,\n\t\t\t\tlongitude: record.lng\n\t\t\t};\n\t\t}\n\t\treturn location;\n\t}\n\n\t/**\n\t * Map a country subdivision record to a subdivision object.\n\t * @param countryCode The country code.\n\t * @param record The country subdivision record.\n\t * @returns The mapped subdivision object.\n\t * @internal\n\t */\n\tprivate static mapCountrySubdivision(\n\t\tcountryCode: string,\n\t\trecord: IUnLocodeCountrySubdivisionRecord\n\t): IUnLocodeSubdivision {\n\t\tconst countryCodeUri = UN_LOCODE_COUNTRIES.find(country => country.value === countryCode)?.uri;\n\t\tconst subdivision: IUnLocodeSubdivision = {\n\t\t\tcode: record.code,\n\t\t\tsubdivisionUri: `${UnLocodes.LOCODE_SUBDIVISION_URI_PREFIX}${countryCode}${record.code}`,\n\t\t\tlabel: record.label,\n\t\t\tcountryCodeUri,\n\t\t\ttype: record.type\n\t\t};\n\t\treturn subdivision;\n\t}\n\n\t/**\n\t * Load a compressed file.\n\t * @param folder The folder to load (e.g., \"countries\" or \"subdivisions\").\n\t * @param countryCode The country code.\n\t * @return The loaded data as an array of records.\n\t * @throws Error if the file cannot be loaded or decompressed.\n\t * @internal\n\t */\n\tprivate static async loadCompressedFile<R, M>(\n\t\tfolder: string,\n\t\tcountryCode: string,\n\t\tmapMethod: (countryCode: string, record: R) => M,\n\t\tcache: { [country: string]: M[] }\n\t): Promise<M[]> {\n\t\tGuards.stringValue(UnLocodes.CLASS_NAME, nameof(countryCode), countryCode);\n\n\t\tconst normalized = countryCode.replace(UnLocodes.LOCODE_COUNTRY_URI_PREFIX, \"\").toUpperCase();\n\t\tconst cached = cache[normalized];\n\t\tif (cached) {\n\t\t\treturn cached;\n\t\t}\n\n\t\ttry {\n\t\t\tconst thisFilename = fileURLToPath(import.meta.url);\n\t\t\tconst thisDirname = path.dirname(thisFilename);\n\t\t\tconst filePath = path.join(thisDirname, `../data/${folder}/`, `${normalized}.json.gz`);\n\t\t\tconst compressed = await fs.readFile(filePath);\n\t\t\tconst jsonBuffer = await Compression.decompress(compressed, CompressionType.Gzip);\n\t\t\tconst records = ObjectHelper.fromBytes<R[]>(jsonBuffer);\n\t\t\tcache[normalized] = records.map(record => mapMethod(normalized, record));\n\t\t} catch {}\n\n\t\treturn cache[normalized] ?? [];\n\t}\n}\n"]}