countrynormalizer 0.0.1

package/README.md

@@ -0,0 +1,160 @@
+# 🌎 Country Data Lookup And Normalizer 🌍
+
+A simple library for consolidation and reverse lookup of common ISO country data fields and calling codes all in one place.
+
+Developers routinely need to mix and match pieces of country data across an application.
+
+Some common examples are:
+
+* Retrieve a country's full name based on an ISO Alpha 2 or Alpha 3 code.
+* Turn a user-entered country name back into an ISO Alpha 2 or 3 code for API standardization.
+* Load a country's flag/flag emoji based on a user input or phone number input.
+* Standardize the name of a country or input from many different references to a country.
+* List all countries on a continent for location selection.
+* Find countries that correspond to a particular phone number's calling code.
+
+There are lots of good libraries out there that handle one of these functions at a time. Turning ISO 3166-1 alpha-2 into full names, or phone number into country flags, and so on and so forth.
+
+It is not uncommon though for application or business use cases to require moving between many of these data points in one application. Yet it can be fairly hard to find all of this data consolidated into a single place.
+
+This library aims to solve a lot of that by consolidating these common country lookups into one place.
+
+## Available Lookups:
+
+### Find Country By Unique:
+
+The `findCountryByUnique(needle: string | number): AllCountryFields | null` can be used to lookup all data for a country based on a single guaranteed unique field. If no country matches the input the function will return `null`.
+
+The guaranteed unique fields are:
+
+* ISO 3166-1 number: The unique ISO 3166-1 number values where there are no duplicate values across all countries.
+* ISO 3166-1 alpha-2: Two letter guaranteed unique country code values.
+* ISO 3166-1 alpha-3: Three letter guaranteed unique country code values.
+* `english_clean`: English country names from the ISO 3166 standard as listed on Wikipedia.
+* `formal_order`: The naturally spoken order of a country's formal name from the ISO 3166 standard. For instance, the `english_clean` for the Netherlands is `Netherlands, Kingdom of the`, while the `formal_order` is `Kingdom of the Netherlands` — the way the country would be referenced in formal international or political conversation.
+* `common_reference`: Maps country names to how they would be referred to in normal casual conversation. So `Kingdom of the Netherlands` is just `Netherlands`. The `Holy See` is `Vatican City`. You can probably use common sense to arrive at most of these.
+* `flag_emoji`: The Unicode standard dictates that all ISO 3166 countries shall have an emoji flag. As such you can search the emoji of a flag as input and retrieve all data for that country.
+
+The returned country structure will match the `AllCountryFields` type and look like this...
+
+```
+{
+      common_reference: "United States of America",
+      english_clean: "United States of America",
+      formal_order: "United States of America",
+      alpha_2: "US",
+      alpha_3: "USA",
+      num_code: 840,
+      demonym_male: "American",
+      demonym_female: "American",
+      gendered_demonym: true,
+      tld: ".us",
+      flag_emoji: "🇺🇸",
+      calling_code: ["1"],
+      continent: "North America",
+    }
+```
+
+### Find All Matching Countries:
+
+You can use `findAllMatchedCountries(needle: string | number): AllCountryFields[]` to get all countries that match a particular data point.
+
+Certain pieces of country data are not unique but still routinely need to be searched for.
+
+A common example of this is calling codes. Most of North America uses the `+1` calling code block. Using a `needle` value of `1` or `+1` will return an array of country data like...
+
+```
+{
+        "common_reference": "United States of America",
+        "english_clean": "United States of America",
+        "formal_order": "United States of America",
+        "alpha_2": "US",
+        "alpha_3": "USA",
+        "num_code": 840,
+        "demonym_male": "American",
+        "demonym_female": "American",
+        "gendered_demonym": true,
+        "tld": ".us",
+        "flag_emoji": "🇺🇸",
+        "calling_code": [
+            "1"
+        ],
+        "continent": "North America"
+    },
+{
+        "common_reference": "United States Minor Outlying Islands",
+        "english_clean": "United States Minor Outlying Islands",
+        "formal_order": "United States Minor Outlying Islands",
+        "alpha_2": "UM",
+        "alpha_3": "UMI",
+        "num_code": 581,
+        "demonym_male": "United States Minor Outlying Islander",
+        "demonym_female": "United States Minor Outlying Islander",
+        "gendered_demonym": true,
+        "tld": ".um",
+        "flag_emoji": "🇺🇲",
+        "calling_code": [
+            "1"
+        ],
+        "continent": "Oceania"
+    },
+{
+        "common_reference": "Canada",
+        "english_clean": "Canada",
+        "formal_order": "Canada",
+        "alpha_2": "CA",
+        "alpha_3": "CAN",
+        "num_code": 124,
+        "demonym_male": "Canadian",
+        "demonym_female": "Canadian",
+        "gendered_demonym": true,
+        "tld": ".ca",
+        "flag_emoji": "🇨🇦",
+        "calling_code": [
+            "1"
+        ],
+        "continent": "North America"
+    },
+
+```
+
+Another use case for this could be if your app has a region-based country selection and you needed all countries in Asia. You could perform a `findAllMatchedCountries('asia')` and get all countries in Asia.
+
+This function still supports singular lookup. Entering something like `findAllMatchedCountries('GB')` will return a single item array like...
+
+```
+[{
+        "common_reference": "United Kingdom",
+        "english_clean": "United Kingdom of Great Britain and Northern Ireland",
+        "formal_order": "United Kingdom of Great Britain and Northern Ireland",
+        "alpha_2": "GB",
+        "alpha_3": "GBR",
+        "num_code": 826,
+        "demonym_male": "British",
+        "demonym_female": "British",
+        "gendered_demonym": true,
+        "tld": ".gb",
+        "flag_emoji": "🇬🇧",
+        "calling_code": [
+            "44"
+        ],
+        "continent": "Europe"
+    },]
+```
+
+Entering a text value into this function that yields no results will return an empty (`[]`) array.
+
+## To-Do List:
+This package was started as part of language classification and news analytics projects I'm working on in my personal time.
+
+I've enjoyed building it out but wanted to publish something for starters so I don't let this languish on my personal computer for too long.
+
+Over the next few weeks (hopefully) I plan to build out the following...
+
+* tld search support should be added to unique lookups since these are unique values.
+* Optimize the search order of data when performing lookups.
+* Clean up some of the `common_reference` values. A lot of these are executive decisions I quickly made and could be better researched or refined.
+* Provide better documentation on the data sources for each of these fields to help assure people of data validity and no collisions of unique data points.
+* Flesh out more complete unit testing. I have a few running right now checking ISO number values but all data values should be validated.
+* Add size optimized lookups for common operations. Currently the `complete.json` object used for country data is rather large and bloats this library. I want to make smaller, tree-shakable functions to handle only certain data queries on the fly.
+* Set up a small website to visualize all this data in an accessible table for using alongside this library. Right now a lot of it is just compiled in a haphazard Google Doc where I did my initial organizing before translating a CSV into a JSON file.

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+import { findCountryByUnique, findAllMatchedCountries } from "./src/findCountryByUnqiue";
+import type { AllCountryFields } from "./types/core";
+export { findCountryByUnique, findAllMatchedCountries };
+export type { AllCountryFields };