countrynormalizer 0.0.1

package/dist/src/findCountryByUnqiue.d.ts

@@ -0,0 +1,52 @@
+import type { AllCountryFields } from "../types/core";
+/**
+ * Searches all guaranteed unique country data fields and returns the single matching country.
+ *
+ * Fields searched (in order):
+ * - ISO 3166-1 numeric code (`num_code`)
+ * - ISO 3166-1 alpha-2 (`alpha_2`)
+ * - ISO 3166-1 alpha-3 (`alpha_3`)
+ * - `english_clean` — English country name from the ISO 3166 standard
+ * - `formal_order` — naturally spoken order of the formal country name
+ * - `flag_emoji` — Unicode flag emoji for the country
+ * - `common_reference` — casual/colloquial country name
+ *
+ * This will **not** search non-unique fields like calling codes, continents, or demonyms.
+ * Use {@link findAllMatchedCountries} for those lookups.
+ *
+ * String inputs must be at least 2 characters. Numeric inputs must be positive.
+ *
+ * @param needle - The search value: a country name, ISO code, numeric code, or flag emoji.
+ * @returns The matching country data, or `null` if no match is found.
+ *
+ * @example
+ * findCountryByUnique("US");    // Returns United States data
+ * findCountryByUnique(840);     // Returns United States data (by numeric code)
+ * findCountryByUnique("🇺🇸");  // Returns United States data (by flag emoji)
+ * findCountryByUnique("xx");    // Returns null
+ */
+export declare const findCountryByUnique: (needle: string | number) => AllCountryFields | null;
+/**
+ * Searches all country data fields — including non-unique fields — and returns every
+ * country that matches the given needle.
+ *
+ * Unlike {@link findCountryByUnique}, this also searches across:
+ * - `calling_code` — phone calling codes (e.g. `"+1"`, `"44"`)
+ * - `continent` — continent name (e.g. `"Asia"`)
+ * - `demonym_male` / `demonym_female` — demonyms (e.g. `"Canadian"`)
+ * - `tld` — top-level domain (e.g. `".uk"`)
+ *
+ * All unique fields (`alpha_2`, `alpha_3`, `english_clean`, `formal_order`,
+ * `common_reference`, `flag_emoji`, `num_code`) are searched as well.
+ *
+ * @param needle - The search value: a country name, ISO code, numeric code, calling code,
+ *   continent name, demonym, TLD, or flag emoji.
+ * @returns An array of all matching countries. Returns an empty array if no matches are found.
+ *
+ * @example
+ * findAllMatchedCountries("+1");     // All countries sharing calling code "1"
+ * findAllMatchedCountries("asia");   // All countries in Asia
+ * findAllMatchedCountries("GB");     // Single-item array with United Kingdom data
+ * findAllMatchedCountries("zzzzz"); // []
+ */
+export declare const findAllMatchedCountries: (needle: string | number) => AllCountryFields[];

package/dist/src/utils/callingCodesValidator.d.ts

@@ -0,0 +1 @@
+export declare const hasMatchingCallingCode: (searchKey: string | number, callingCodes: string[]) => boolean;

package/dist/src/utils/domainValidator.d.ts

@@ -0,0 +1 @@
+export declare const matchesCleanedDomain: (searchKey: string, countryDomain: string) => boolean;

package/dist/types/core.d.ts

@@ -0,0 +1,17 @@
+export interface AllCountryFields {
+    common_reference: string;
+    english_clean: string;
+    formal_order: string;
+    alpha_2: string;
+    alpha_3: string;
+    num_code: number;
+    demonym_male: string;
+    demonym_female: string;
+    gendered_demonym: boolean;
+    tld: string;
+    flag_emoji: string;
+    calling_code: string[];
+    continent: string;
+}
+export type ContactCountryFields = Pick<AllCountryFields, "tld" | "flag_emoji" | "calling_code">;
+export type UniqueCountryFields = Pick<AllCountryFields, "english_clean" | "formal_order" | "alpha_2" | "alpha_3" | "num_code">;

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "countrynormalizer",
+  "version": "0.0.1",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "bun run build.ts",
+    "extract-data": "bun ./tools/build-data.ts"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "@types/jest": "^30.0.0",
+    "@types/lodash": "^4.17.24",
+    "csvtojson": "^2.0.14",
+    "jest": "^30.2.0",
+    "lodash": "^4.17.23"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  }
+}