{"analyzedAt":"2022-07-09T08:35:17.745Z","collected":{"metadata":{"name":"iso-locale-tools","scope":"unscoped","version":"0.1.1","description":"All world countries and data points about them, as well as tools for interfacing with that data.","keywords":["countries","world countries","world","json","iso-3166","iso-3166-1","iso-4217","iso-639","iso-639-3","ietf","iso-15924","iana","bcp47","languages","locales","locale","currency","currencies","localization","location","geography","governance","tz-database","tz","tz-timezones","timezones","ioc","tld","idd"],"date":"2021-11-14T19:48:00.439Z","author":{"name":"Sara Pope","email":"sarafpope@gmail.com"},"publisher":{"username":"gretzky","email":"sfed617@gmail.com"},"maintainers":[{"username":"gretzky","email":"sfed617@gmail.com"}],"repository":{"type":"git","url":"git+https://github.com/gretzky/iso-locale-tools.git"},"links":{"npm":"https://www.npmjs.com/package/iso-locale-tools","homepage":"https://github.com/gretzky/iso-locale-tools#readme","repository":"https://github.com/gretzky/iso-locale-tools","bugs":"https://github.com/gretzky/iso-locale-tools/issues"},"license":"MIT","dependencies":{"axios":"^0.24.0","date-fns":"^2.25.0","date-fns-tz":"^1.1.6"},"devDependencies":{"tsdx":"^0.14.1","typescript":"^4.4.4"},"releases":[{"from":"2022-06-09T00:00:00.000Z","to":"2022-07-09T00:00:00.000Z","count":0},{"from":"2022-04-10T00:00:00.000Z","to":"2022-07-09T00:00:00.000Z","count":1},{"from":"2022-01-10T00:00:00.000Z","to":"2022-07-09T00:00:00.000Z","count":1},{"from":"2021-07-09T00:00:00.000Z","to":"2022-07-09T00:00:00.000Z","count":4},{"from":"2020-07-09T00:00:00.000Z","to":"2022-07-09T00:00:00.000Z","count":4}],"hasSelectiveFiles":true,"readme":"# iso-locale-tools\n\nAll world countries and data points about them, as well as tools for interfacing with that data.\n\n## Installation\n\nInstall with npm or yarn.\n\n```bash\nnpm install iso-locale-tools\nyarn add iso-locale-tools\n```\n\n## Usage\n\nThe full JSON array of all world countries and information about them lives in `src/data/countries-expanded.json`.\n\nEach country is represented as an object.\n\n- `name`\n  - `common`: common name (in English)\n  - `official`: officially recognized name (in English)\n  - `native`: list of names in the country's recognized languages\n    - `[key: ISO_639_3]`: ISO 639-3 language code\n      - `common`: common name (in native language)\n      - `official`: officially recognized name (in native language)\n  - `alternates`: array of alternate name spellings\n- `flag`: unicode string flag\n- `cca2`: [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) code\n- `cca3`: [ISO 3166-1 alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3) code\n- `ccn3`: [ISO 3166-1 numeric](https://en.wikipedia.org/wiki/ISO_3166-1_numeric) code\n- `ioc`: [International Olympic Committee](https://en.wikipedia.org/wiki/International_Olympic_Committee) code\n- `governance`\n  - `isSovereign`: whether or not the country is independent (i.e. is self-governing)\n  - `governingBody`: the country that governs the dependency (`undefined` if `isSovereign` is true)\n  - `isUNMember`: whether or not the country is a member of the UN (`undefined` if `isSovereign` is false)\n  - `isEU`: (european countries only) whether or not the country is a member of the EU\n  - `isSchengen`: (european countries only) whether or not the country is a member of the [Schengen Area](https://en.wikipedia.org/wiki/Schengen_Area)\n  - `isEurozone`: (european countries only) whether or not the country is a part of the [Eurozone](https://en.wikipedia.org/wiki/Eurozone), i.e. whether or not they use the Euro currency\n- `languages`\n  - `official`: an array of officially recognized languages\n    - `name`:\n      - `common`: the name of the language in English\n      - `native`: the name of the language in that language\n    - `iso639_3`: [ISO639-3](https://en.wikipedia.org/wiki/ISO_639-3) language code\n    - `bcp47`: [BCP47](https://en.wikipedia.org/wiki/IETF_language_tag) tag\n    - `iso14924`: [ISO15924](https://en.wikipedia.org/wiki/ISO_15924) script tag\n    - `iana`: array of assigned [IANA](https://en.wikipedia.org/wiki/IETF_language_tag) tags\n    - `isExtinct`: whether or not the language is no longer spoken\n    - `isSpurious`: whether or not the language is [spurious](https://en.wikipedia.org/wiki/Spurious_languages), i.e. questioned if it ever existed\n  - `spoken`: list of [ISO639-3](https://en.wikipedia.org/wiki/ISO_639-3) language tags of languages spoken in the country, but are not recognized as 'official' languages\n- `geography`\n  - `coordinates`: numeric coordinates of the center of the country\n    - `latitude`\n    - `longitude`\n  - `isLandlocked`: whether or not the country is landlocked (not bordering the ocean)\n  - `capitalCity`: a list of capital cities\n  - `landArea`: size of the country in km<sup>2</sup>\n  - `region`: the region the country is in (e.g. 'americas', 'europe')\n  - `subregion`: the subregion of the country (e.g. `carribbean`)\n  - `borderCountries`: list of countries by their [ISO 3166-1 alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3) codes that border the country\n- `locale`\n  - `ietf`: a list of [IETF](https://en.wikipedia.org/wiki/IETF_language_tag) locale codes (e.g. `en-US`)\n  - `measurementSystem`: system of measurement in use\n  - `drivingSide`: driving side\n  - `hourClock`: type of clock used\n  - `timezones`: list of [tz database timezones](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones)\n    - `name`: name of timezone\n    - `type`: the type of timezone (primary or alias)\n    - `linkedTo`: (if alias) the primary timezone this timezone links to\n    - `utcOffset`: hours offset from UTC\n    - `dstOffset`: hours offset from UTC during DST (if country doesn't observe DST, this is the same value as UTC offset)\n  - `dateFormats`: date formats for each IETF locale\n    - key is the IETF locale name\n    - value is the date format, where:\n      - `G` = era\n      - `y` = year\n      - `M` = month\n      - `d` = day\n  - `weekStartsOn`: which day is the first day of the week on the calendar\n  - `distanceUnit`: the unit of distance used (kilometer or mile)\n  - `temperatureMeasurement`: the unit of temperature (celsius or fahrenheit)\n- `currencies`: list of accepted currencies\n  - `name`: official currency name (in English)\n  - `shortName`: the name of the currency itself (e.g. 'dollar' as opposed to 'US Dollar')\n  - `iso4217`: [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) code\n  - `isoNumeric`: [ISO 4217 numeric](https://en.wikipedia.org/wiki/ISO_4217) code\n  - `symbol`: unicode symbol (e.g. '$')\n  - `subunit`: subunit to whole value (e.g. 'cent')\n  - `subunitToUnit`: number of subunits to reach a whole unit value (e.g. 100 cents = 1 dollar)\n  - `prefix`: symbol that prefixes a currency amount (e.g. '$1')\n  - `suffix`: symbol that suffixes a currency amonut (e.g. '1€')\n  - `decimalMark`: symbol that denotes a decimal place\n  - `decimalPlaces`: number of decimal places rounded to\n  - `thousansSeparator`: symbol to denote thousands separation\n- `tld`: list of [top-level domains](https://en.wikipedia.org/wiki/Top-level_domain) used\n- `idd`: [international dialing direct](https://en.wikipedia.org/wiki/List_of_country_calling_codes) info\n  - `prefix`: geographical code prefix (e.g. +1 for US)\n  - `suffixes`: list of suffixes assigned (e.g. 201 in US)\n  - `callingCodes`: list of calling codes (combinations of the prefix and each suffix - e.g. +1201)\n- `subdivisions`: list of [ISO 3166-2](https://en.wikipedia.org/wiki/ISO_3166-2) subdivisions of each country\n  - `name`: name of the subdivision in the country's recognized languages\n    - `[key: ISO_639_3]`: ISO 639-3 language code\n      - `official`: official subdivison name\n      - `common`: locally used name variant\n      - `native`: official name in non-alphanumeric script language (e.g. arabic, cyrillic)\n\nThere is also a truncated list (`src/data/countries.json`) that abbreviates and filters out certain data to reduce file size.\n\n**Full country list vs. truncated country list**\n\n| Object | `countries-expanded.json` | `countries.json` |\n| -- | -- | -- |\n| `languages.official` | A list of full language objects | A list of [ISO639-3](https://en.wikipedia.org/wiki/ISO_639-3) language codes |\n| `currencies` | A list of full currency objects | A list of [ISO4217](https://en.wikipedia.org/wiki/ISO_4217) currency codes |\n| `locale.timezones` | A list of full timezone objects | A list of [tz database timezone names](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) |\n| `subdivisions` | A list of subdivision objects | `undefined` |\n\n**Note:** `subdivisions` is removed from `countries.json` because for most countries, it's a huge list and many times isn't needed.\n\n## API\n\nThis package contains datasets for multiple different things related to world countries. The datasets can be found in [`src/data/`](./src/data).\n\n```ts\nimport { \n  countriesExpanded, // full countries list\n  countries, // truncated country list\n  currencies, // world currencies list\n  languages, // world languages list\n  timezones, // tz database timezones list\n} from 'iso-locale-tools'\n```\n\n### Types\n\nThere are several types and enumerators to assist in handling different ISO codes.\n\n#### Countries\n\n```ts\n// ISO3166-1 alpha2 (cca2) codes\nenum ISO3166_1_Alpha2 {}\nISO3166_1_Alpha2.AX // \"AX\"\n\n// ISO3166-1 alpha2 codes keyed by country name\nenum ISO3166_1_Alpha2ByCountry {} \nISO3166_1_Alpha2ByCountry.denmark // \"DK\"\n\n// ISO3166-1 alpha3 (cca3) codes\nenum ISO3166_1_Alpha3 {}\nISO3166_1_Alpha3.ALA // \"ALA\"\n\n// ISO3166-1 alpha3 codes keyed by country name\nenum ISO3166_1_Alpha3ByCountry {}\nISO3166_1_Alpha3ByCountry.denmark // \"DNK\" \n\n// ISO3166 numeric (ccn3) codes\nenum ISO3166_1_NumericByCountry {}\nISO3166_1_NumericByCountry.british_virgin_islands // \"092\"\n\n// ISO3166-2 subdivision codes\nenum ISO3166_2 {} // ISO3166-2 subdivision codes\nISO3166_2.BT_42 // \"BT-42\"\n```\n\n#### Currency\n\n```ts\n// currency object type\ntype Currency = {\n  name: CurrencyNamesByISO4217 | string\n  shortName: CurrencyNamesByISO4217\n  iso_4217: ISO4217\n  symbol: CurrencySymbolsByISO4217 | string\n  subunit: string | null\n  subunitToUnit: number | null\n  prefix: string | null\n  suffix: string | null\n  decimalMark: string | null\n  decimalPlaces: number | null\n  thousandsSeparator: string | null\n}\n\n// ISO4217 currency codes\nenum ISO4217 {}\nISO4217.USD // \"USD\"\n\n// currency names by ISO4217 codes\nenum CurrencyNamesByISO4217 {}\nCurrencyNamesByISO4217.USD // \"United States Dollar\"\n\n// currency 'short' names by ISO4217\nenum CurrencyShortNamesByISO4217 {}\nCurrencyShortNamesByISO4217.USD // \"dollar\"\n\n// currency symbols by ISO4217\nenum CurrencySymbolsByISO4217 {}\nCurrencySymbolsByISO4217.USD // \"$\"\n```\n\n#### Language\n\n```ts\ntype Language = {\n  name: {\n    common: string\n    native: string | null\n    alternates?: string[]\n  },\n  iso639_3: ISO639_3,\n  bcp47: BCP47,\n  iso15924: ISO15924\n  iana: string[]\n  countries?: ISO3166_1_Alpha2\n  isExtinct: boolean\n  isSpurious: boolean\n}\n\n// ISO639-3 language codes\nenum ISO639_3 {}\nISO639_3.eng // \"eng\"\n\n// BCP47 language tags\nenum BCP47 {}\nBCP47.abq_Cyrl // \"abq-Cyrl\"\n\n// ISO15924 codes\nenum ISO15924 {}\nISO15924.cyrl //\n```\n\n#### Locale\n\n```ts\ntype Locale = {\n  ietf: IETF[]\n  drivingSide: DrivingSide | DrivingSides\n  measurementSystem: MeasurementSystem | MeasurementSystems\n  hourClock: HourClock | HourClocks\n  timezones: Timezone[] | TZTimezones[]\n  dateFormats: {\n    [key in IETF]: string\n  }\n  weekStartsOn: WeekStartDay | WeekStartDays\n  distanceUnit: DistanceUnit | DistanceUnits\n  temperatureUnit: TemperatureUnit | TemperatureUnit\n}\n\n// distance unit -- can use either the type or the enum\ntype DistanceUnit = \"kilometer\" | \"mile\"\nenum DistanceUnits {\n  KM = \"kilometer\",\n  MI = \"mile\"\n}\n\n// temp unit -- can use either the type or the enum\ntype TemperatureUnit = \"celsius\" | \"fahrenheit\"\nenum TemperatureUnits {\n  C = \"celsius\",\n  F = \"fahrenheit\"\n}\n\n// week start day -- can use either the type or the enum\ntype WeekStartDay = \"friday\" | \"saturday\" | \"sunday\" | \"monday\"\nenum WeekStartDays {\n  FRIDAY = \"friday\",\n  SATURDAY = \"saturday\",\n  SUNDAY = \"sunday\",\n  MONDAY = \"monday\"\n}\n\n// driving side -- can use either the type or the enum\ntype DrivingSide = \"left\" | \"right\"\nenum DrivingSides {\n  LEFT = \"left\",\n  RIGHT = \"right\"\n}\n\n// measurement system -- can use either the type or the enum\ntype MeasurementSystem = \"metric\" | \"imperial\"\nenum MeasurementSystems {\n  METRIC = \"metric\",\n  IMPERIAL = \"imperial\"\n}\n\n// hour clock -- can use either the type or the enum\ntype HourClock = \"12hr\" | \"24hr\" | \"mixed\"\nenum HourClocks {\n  AM_PM = \"12hr\",\n  MILITARY = \"24hr\",\n  MIXED = \"mixed\"\n}\n\n// timezone object\ntype Timezone = {\n  name: Timezones\n  type: \"canonical\" | \"link\"\n  linkedTo: string | null\n  utcOffset: string\n  dstOffset: string\n}\n\n// IETF locale codes\nenum IETF {}\nIETF.en_CA // \"en-CA\"\n\n// tz database timezone names\nenum TZTimezones {}\nTZTimezones.windhoek // \"Africa/Windhoek\"\n```\n\n#### Location\n\n```ts\ntype Location = {\n  coordinates: Coordinates\n  isLandlocked: boolean\n  borderCountries: ISO3166_1_Alpha3\n  capitalCity: string[]\n  landArea: number\n  region: Regions\n  subregion: Subregions\n}\n\n// coordinates object\ntype Coordinates = {\n  latitude: number\n  longitude: number\n}\n\n// regions\nenum Regions {}\nRegions.oceania // \"oceania\"\n\n// subregions\nenum Subregions {}\nSubregions.australia_new_zealand // \"Australia and New Zealand\"\n```\n\n### Utils\n\n#### Countries\n\n- **`countryNameToKey(name: string): CountryKey`**: gets the country name key for a country by it's common name (`name.common`)\n- **`removeDiacritics(str: string): string`**: Removes diacritics (accented characters, etc.) from a string\n\n```ts\nimport { countryNameToKey, removeDiacritics } from 'iso-locale-tools'\n\nconst countryKey = countryNameToKey(\"Svalbard and Jan Mayen\")\n// returns `svalbard_jan_mayen`\nconst cca2 = ISO3166_1_Alpha2ByCountry[countryKey]\n// equivalent to ISO3166_1_Alpha2ByCountry.svalbard_jan_mayen\n\nconst aland = removeDiacritics(\"Åland Islands\")\n// returns \"Aland Islands\"\n```\n\n#### Currency\n\n- **`getConversionRate({ from, to }: { from: ISO4217, to: ISO4217 }): number | Error`**: returns the conversion rate between 2 currencies, returns an error if one encountered. This function utilizes the free version of the [currconv api](https://www.currencyconverterapi.com/). \n\n```ts\nimport { getConversionRate, ISO4217 } from 'iso-locale-tools'\n\nconst conversionRate = getConversionRate({\n  from: ISO4217.USD,\n  to: ISO4217.EUR\n})\n// returns the conversion rate from the us dollar to euro\n```\n\n#### Locale\n\n- **`convertDistance(distance: number, fromUnit: \"kilometer\" | \"mile\"): number`**: converts a distance from a given unit to the opposite unit\n- **`getDateFnsLocale(locale: IETF, { fallbackLocale }: { fallbackLocale: DateFnsLocale }): DateFnsLocale`**: returns a [date-fns locale object](https://date-fns.org/v2.25.0/docs/Locale). if a direct match is not found, it'll try to detect the closest locale, otherwise it uses a fallback. the default fallback is `en-US`.\n- **`getDatePatternForLocale(locale: IETF)`**: gets the date format pattern (e.g. 'yyyy-MM-dd') for a given locale\n- **`getDateTimeForTimezone({ date, dateTimeFormat, timezone, serverTimezone }: { date?: Date | number | string, dateTimeFormat: string, timezone: TZTimezone, serverTimezone?: TZTimezone }): Date`**: returns a date formatted and converted to a given timezone. if `date` is not provided, it fallsback to `Date.now()`. `serverTimezone` is the timezone to compare against, if necessary (fallback is UTC).\n\n```ts\nimport { \n  convertDistance,\n  getDateFnsLocale,\n  getDatePatternForLocale, \n  getDateTimeForTimezone \n} from 'iso-locale-tools'\n\nconst distance = convertDistance(2, \"kilometer\")\n// returns 1.242742 (miles)\n\nconst dateFnsLocaleDirect = getDateFnsLocale(\"en-AU\") // returns the en-AU locale\nconst dateFnsLocaleClosest = getDateFnsLocale(\"es-PY\") // there is no 'es-PY' locale, so this will return the es locale\nconst dateFnsLocaleFallback = getDateFnsLocale(\"aay\") // there is no 'aay' locale or a closest match, so this will return the 'en-US' default fallback locale\nconst dateFnsLocaleFallbackCustom = getDateFnsLocale(\"aay\", { fallbackLocale: \"en-CA\" }) // will return en-CA as a fallback\n\nconst datePattern = getDatePatternForLocale(\"nl-AW\") // returns \"dd-MM-yyyy\"\n\nconst dateTimeInTimezone = getDateTimeForTimezone({\n  date: 1636911831222,\n  dateTimeFormat: \"dd-MM-yyyy HH:mm\",\n  timezone: \"Africa/Windhoek\",\n})\n// returns \"14-11-2021 19:44\"\n```\n\n#### Location\n\n- **`bearingToDirection(bearing: number): Directions | undefined`**: converts a bearing (in degrees) to a given cardinal direction\n- **`getCenterOfCoordinates(coordinates: Coordinates[]): Coordinates`**: finds the direct center of a group of coordinates\n- **`getRhumbLine(fromLongitude: number, toLongitude: number): number`**: gets a [rhumb line](https://en.wikipedia.org/wiki/Rhumb_line) between 2 longitudes\n- **`geographicDistanceTo({ from, to, unit, useRhumbLine }: { from: Coordinates, to: Coordinates, unit: DistanceUnit, useRhumbLine?: boolean }): number`**: get the [great-circle distance](https://en.wikipedia.org/wiki/Great-circle_distance) between 2 points (using [haversine formula](https://en.wikipedia.org/wiki/Versine#hav)). set `useRhumbLine` to `true` to get the distance between 2 points using a rhumb line.\n- **`bearingDistanceTo({ from, to, useRhumbLine }: { from: Coordinates, to: Coordinates, useRhumbLine?: boolean }): { initialBearing: number, finalBearing: number})`**: returns the initial bearing from start point to destination point, and the final bearing which differs by varying degrees according to the lat/long. set `useRhumbLine` to `true` to get the bearings over a rhumb line.\n\n```ts\nimport {\n  bearingToDirection,\n  getCenterOfCoordinates,\n  getRhumbLine,\n  geographicDistanceTo,\n  bearingDistanceTo\n} from 'iso-locale-tools'\n\nconst direction = bearingToDirection(261)\n// returns 'WNW'\n\nconst location1 = { latitude: 12.5, longitude: -69.9 }\nconst location2 = { latitude: 52.5, longitude: 5.75 }\n\nconst center = getCenterOfCoordinates([\n  location1,\n  location2\n])\n// returns { latitude: 38.44160133305245, longitude: -42.280221828555504 }\n\nconst rhumbLine = getRhumbLine(location1.longitude, location2.longitude)\n// returns 1.3203415791337105\n\nconst distance = geographicDistanceTo({ from: location1, to: location2, unit: \"mile\" })\n// returns 12792.535602738117\n\nconst distanceUsingRhumbLine = geographicDistanceTo({ from: location1, to: location2, unit: \"kilometer\", useRhumbLine: true })\n// returns 8156.327629644782\n\nconst bearing = bearingDistanceTo({ from: location1, to: location2 })\n// returns { initialBearing: 51.51700060782139, finalBearing: 231.5170006078214 }\n\nconst bearingUsingRhumbLine = const bearing = bearingDistanceTo({ from: location1, to: location2, useRhumbLine: true })\n// returns { initialBearing: 56.90674499795489, finalBearing: 236.9067449979549 }\n```\n\n## Acknowledgements\n\n- [https://github.com/mledoze/countries](https://github.com/mledoze/countries)\n- [https://github.com/countries/countries](https://github.com/countries/countries)"},"npm":{"downloads":[{"from":"2022-07-08T00:00:00.000Z","to":"2022-07-09T00:00:00.000Z","count":7},{"from":"2022-07-02T00:00:00.000Z","to":"2022-07-09T00:00:00.000Z","count":15},{"from":"2022-06-09T00:00:00.000Z","to":"2022-07-09T00:00:00.000Z","count":260},{"from":"2022-04-10T00:00:00.000Z","to":"2022-07-09T00:00:00.000Z","count":574},{"from":"2022-01-10T00:00:00.000Z","to":"2022-07-09T00:00:00.000Z","count":662},{"from":"2021-07-09T00:00:00.000Z","to":"2022-07-09T00:00:00.000Z","count":783}],"starsCount":0},"github":{"starsCount":1,"forksCount":0,"subscribersCount":2,"issues":{"count":0,"openCount":0,"distribution":{"3600":0,"10800":0,"32400":0,"97200":0,"291600":0,"874800":0,"2624400":0,"7873200":0,"23619600":0,"70858800":0,"212576400":0},"isDisabled":false},"contributors":[{"username":"gretzky","commitsCount":20}],"commits":[{"from":"2022-07-02T00:00:00.000Z","to":"2022-07-09T00:00:00.000Z","count":0},{"from":"2022-06-09T00:00:00.000Z","to":"2022-07-09T00:00:00.000Z","count":0},{"from":"2022-04-10T00:00:00.000Z","to":"2022-07-09T00:00:00.000Z","count":0},{"from":"2022-01-10T00:00:00.000Z","to":"2022-07-09T00:00:00.000Z","count":0},{"from":"2021-07-09T00:00:00.000Z","to":"2022-07-09T00:00:00.000Z","count":20}]},"source":{"files":{"readmeSize":17543,"testsSize":0},"linters":["editorconfig"],"outdatedDependencies":{"axios":{"required":"^0.24.0","stable":"0.27.2","latest":"1.0.0-alpha.1"}}}},"evaluation":{"quality":{"carefulness":0.45999999999999996,"tests":0,"health":0.75,"branding":0},"popularity":{"communityInterest":4,"downloadsCount":191.33333333333334,"downloadsAcceleration":2.0135083713850834,"dependentsCount":0},"maintenance":{"releasesFrequency":0.4715753424657535,"commitsFrequency":0.23013698630136986,"openIssues":0.7,"issuesDistribution":0.7}},"score":{"final":0.49581383465525075,"detail":{"quality":0.44812786352026723,"popularity":0.03522476108563823,"maintenance":0.9972765977691349}}}