Skip to content

docs: recommend string identifiers for numeric codes #170

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
bhousel merged 1 commit into from
Apr 24, 2026
Merged

docs: recommend string identifiers for numeric codes #170

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 12 additions & 15 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.


Expand Down Expand Up @@ -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

Expand All @@ -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}
Expand All @@ -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'
Expand Down Expand Up @@ -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'
Expand Down Expand Up @@ -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'
Expand Down Expand Up @@ -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 '🇮🇲'
Expand Down Expand Up @@ -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'
Expand Down Expand Up @@ -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}]
Expand All @@ -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}]
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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'
Expand All @@ -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'
Expand All @@ -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'
Expand All @@ -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']
Expand Down
Loading