From 9189710b6187d04a5db9df39d72768140401f775 Mon Sep 17 00:00:00 2001 From: Bryan Housel Date: Fri, 24 Apr 2026 09:34:55 -0400 Subject: [PATCH] docs: recommend string identifiers for numeric codes - add warning callouts about leading-zero numeric literal hazards - stop advertising bare numeric identifier examples in the README - keep runtime behavior unchanged --- README.md | 27 ++++++++++++--------------- 1 file changed, 12 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index ab628ad..d644c32 100644 --- a/README.md +++ b/README.md @@ -108,6 +108,12 @@ The same method can convert from other identifiers. iso1A2Code('Q145'); // returns 'GB' ``` +> [!WARNING] +> Numeric identifiers are accepted for convenience, but string identifiers are recommended. +> In JavaScript, leading-zero numeric literals like `021`, `030`, or `053` can be misparsed in non-strict code before `country-coder` receives them. +> Prefer string values like `'021'`, `'030'`, and `'053'` for ISO numeric-3 and UN M49 identifiers. +> Numeric identifier support may be deprecated in a future release. + Read the [full API reference](#api-reference) to see everything `country-coder` can do. @@ -161,6 +167,12 @@ This package is kept intentionally minimal. However, if you find a bug or have a * [RegionFeatureProperties](#RegionFeatureProperties) * [RegionFeatureCollection](#RegionFeatureCollection) +> [!WARNING] +> Numeric identifiers are accepted for convenience, but string identifiers are recommended. +> In JavaScript, leading-zero numeric literals like `021`, `030`, or `053` can be misparsed in non-strict code before `country-coder` receives them. +> Prefer string values like `'021'`, `'030'`, and `'053'` for ISO numeric-3 and UN M49 identifiers. +> Numeric identifier support may be deprecated in a future release. + ## Methods @@ -175,7 +187,6 @@ feature([0, 90]); // returns null feature('GB'); // returns {United Kingdom} feature('GBR'); // returns {United Kingdom} feature('826'); // returns {United Kingdom} -feature(826); // returns {United Kingdom} feature('Q145'); // returns {United Kingdom} feature('🇬🇧'); // returns {United Kingdom} feature('.uk'); // returns {United Kingdom} @@ -199,7 +210,6 @@ iso1A2Code([-4.5, 54.2], { level: 'territory' }); // returns 'IM' iso1A2Code([0, 90]); // returns null iso1A2Code('GBR'); // returns 'GB' iso1A2Code('826'); // returns 'GB' -iso1A2Code(826); // returns 'GB' iso1A2Code('Q145'); // returns 'GB' iso1A2Code('🇬🇧'); // returns 'GB' iso1A2Code('.uk'); // returns 'GB' @@ -237,7 +247,6 @@ iso1A3Code([-4.5, 54.2], { level: 'territory' }); // returns 'IMN' iso1A3Code([0, 90]); // returns null iso1A3Code('GB'); // returns 'GBR' iso1A3Code('826'); // returns 'GBR' -iso1A3Code(826); // returns 'GBR' iso1A3Code('Q145'); // returns 'GBR' iso1A3Code('🇬🇧'); // returns 'GBR' iso1A3Code('.uk'); // returns 'GBR' @@ -352,7 +361,6 @@ wikidataQID([0, 90]); // returns null wikidataQID('GB'); // returns 'Q145' wikidataQID('GBR'); // returns 'Q145' wikidataQID('826'); // returns 'Q145' -wikidataQID(826); // returns 'Q145' wikidataQID('🇬🇧'); // returns 'Q145' wikidataQID('.uk'); // returns 'Q145' wikidataQID('UK'); // returns 'Q145' @@ -390,7 +398,6 @@ emojiFlag([0, 90]); // returns null emojiFlag('GB'); // returns '🇬🇧' emojiFlag('GBR'); // returns '🇬🇧' emojiFlag('826'); // returns '🇬🇧' -emojiFlag(826); // returns '🇬🇧' emojiFlag('Q145'); // returns '🇬🇧' emojiFlag('UK'); // returns '🇬🇧' emojiFlag('IM'); // returns '🇮🇲' @@ -427,7 +434,6 @@ ccTLD([0, 90]); // returns null ccTLD('GB'); // returns '.uk' ccTLD('GBR'); // returns '.uk' ccTLD('826'); // returns '.uk' -ccTLD(826); // returns '.uk' ccTLD('Q145'); // returns '.uk' ccTLD('UK'); // returns '.uk' ccTLD('IM'); // returns '.im' @@ -465,7 +471,6 @@ featuresContaining([0, 90]); // returns [] featuresContaining('GB'); // returns [{United Kingdom}, {United Nations}, {World}] featuresContaining('GBR'); // returns [{United Kingdom}, {United Nations}, {World}] featuresContaining('826'); // returns [{United Kingdom}, {United Nations}, {World}] -featuresContaining(826); // returns [{United Kingdom}, {United Nations}, {World}] featuresContaining('Q145'); // returns [{United Kingdom}, {United Nations}, {World}] featuresContaining('🇬🇧'); // returns [{United Kingdom}, {United Nations}, {World}] featuresContaining('.uk'); // returns [{United Kingdom}, {United Nations}, {World}] @@ -488,7 +493,6 @@ Returns all the the features that match or are contained within the given identi featuresIn('CN'); // returns [{China}, {Mainland China}, {Hong Kong}, {Macau}] featuresIn('CHN'); // returns [{China}, {Mainland China}, {Hong Kong}, {Macau}] featuresIn('156'); // returns [{China}, {Mainland China}, {Hong Kong}, {Macau}] -featuresIn(156); // returns [{China}, {Mainland China}, {Hong Kong}, {Macau}] featuresIn('Q148'); // returns [{China}, {Mainland China}, {Hong Kong}, {Macau}] featuresIn('🇨🇳'); // returns [{China}, {Mainland China}, {Hong Kong}, {Macau}] featuresIn('.cn'); // returns [{China}, {Mainland China}, {Hong Kong}, {Macau}] @@ -505,7 +509,6 @@ Returns a new feature with the `properties` of the feature matching `id` and the aggregateFeature('CN'); // returns Mainland China, Hong Kong, and Macau as one feature aggregateFeature('CHN'); // returns Mainland China, Hong Kong, and Macau as one feature aggregateFeature('156'); // returns Mainland China, Hong Kong, and Macau as one feature -aggregateFeature(156); // returns Mainland China, Hong Kong, and Macau as one feature aggregateFeature('Q148'); // returns Mainland China, Hong Kong, and Macau as one feature aggregateFeature('🇨🇳'); // returns Mainland China, Hong Kong, and Macau as one feature aggregateFeature('.cn'); // returns Mainland China, Hong Kong, and Macau as one feature @@ -553,7 +556,6 @@ isInEuropeanUnion('EU'); // returns true isInEuropeanUnion('DE'); // returns true isInEuropeanUnion('DEU'); // returns true isInEuropeanUnion('276'); // returns true -isInEuropeanUnion(276); // returns true isInEuropeanUnion('Q183'); // returns true isInEuropeanUnion('🇩🇪'); // returns true isInEuropeanUnion('.de'); // returns true @@ -584,7 +586,6 @@ isInUnitedNations('EU'); // returns true isInUnitedNations('DE'); // returns true isInUnitedNations('DEU'); // returns true isInUnitedNations('276'); // returns true -isInUnitedNations(276); // returns true isInUnitedNations('Q183'); // returns true isInUnitedNations('🇩🇪'); // returns true isInUnitedNations('.de'); // returns true @@ -615,7 +616,6 @@ driveSide('EU'); // returns null driveSide('GB'); // returns 'left' driveSide('GBR'); // returns 'left' driveSide('826'); // returns 'left' -driveSide(826); // returns 'left' driveSide('Q145'); // returns 'left' driveSide('🇬🇧'); // returns 'left' driveSide('.uk'); // returns 'left' @@ -641,7 +641,6 @@ roadSpeedUnit('EU'); // returns null roadSpeedUnit('GB'); // returns 'mph' roadSpeedUnit('GBR'); // returns 'mph' roadSpeedUnit('826'); // returns 'mph' -roadSpeedUnit(826); // returns 'mph' roadSpeedUnit('Q145'); // returns 'mph' roadSpeedUnit('🇬🇧'); // returns 'mph' roadSpeedUnit('.uk'); // returns 'mph' @@ -667,7 +666,6 @@ roadHeightUnit('EU'); // returns null roadHeightUnit('GB'); // returns 'ft' roadHeightUnit('GBR'); // returns 'ft' roadHeightUnit('826'); // returns 'ft' -roadHeightUnit(826); // returns 'ft' roadHeightUnit('Q145'); // returns 'ft' roadHeightUnit('🇬🇧'); // returns 'ft' roadHeightUnit('.uk'); // returns 'ft' @@ -692,7 +690,6 @@ callingCodes('EU'); // returns [] callingCodes('GB'); // returns ['44'] callingCodes('GBR'); // returns ['44'] callingCodes('826'); // returns ['44'] -callingCodes(826); // returns ['44'] callingCodes('Q145'); // returns ['44'] callingCodes('🇬🇧'); // returns ['44'] callingCodes('.uk'); // returns ['44']