i18n-countries-continents 1.0.2 → 1.0.3

package/CHANGELOG.md

@@ -5,6 +5,22 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.0.3] - 2026-03-27
+
+### Changed
+- Rewrote README with fixed emoji rendering (broken flag/map emojis on npm)
+- Added badges (npm version, downloads, license, TypeScript)
+- Added yarn and pnpm installation commands
+- Added sub-path imports section showing all tree-shakeable entry points
+- Added separate Node.js ESM and CommonJS usage examples
+- Added `SUPPORTED_LANGUAGES` constant to API reference
+- Improved TypeScript types section with inline comments
+- Replaced plain lists with tables for Data Coverage (Countries, Languages)
+- Fixed duplicate `---` dividers in document
+- Fixed `Data Format` section that incorrectly referenced `src/data/` (internal source path)
+- Improved React, Vue, and Angular examples with more realistic code
+- Cleaned up API reference descriptions with parameter documentation
+
 ## [1.0.2] - 2025-03-10
 
 ### Fixed

package/README.md

@@ -1,6 +1,11 @@
 # i18n-countries-continents
 
-Get country, continent, and city names in different languages. **250 countries**, **7 continents**, and **4,010 cities** with full translations in 5 languages. Works in React, Angular, Vue, Node.js, and any JavaScript environment.
+Get country, continent, and city names in different languages. **250 countries**, **7 continents**, and **4,010 cities** with full translations in **5 languages**. Works in React, Angular, Vue, Svelte, Node.js, and any JavaScript environment.
+
+[![npm version](https://img.shields.io/npm/v/i18n-countries-continents.svg)](https://www.npmjs.com/package/i18n-countries-continents)
+[![npm downloads](https://img.shields.io/npm/dm/i18n-countries-continents.svg)](https://www.npmjs.com/package/i18n-countries-continents)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)
 
 ## Installation
 
@@ -8,18 +13,30 @@ Get country, continent, and city names in different languages. **250 countries**
 npm install i18n-countries-continents
 ```
 
+```sh
+yarn add i18n-countries-continents
+```
+
+```sh
+pnpm add i18n-countries-continents
+```
+
+---
+
 ## Features
 
-- 🌍 **250 countries** - Complete coverage of all world countries
-- � **Country flags** - Flag emoji for every country
-- �🗺️ **7 continents** - All continents included
-- 🏙️ **4,010 cities** - Major cities from around the world
-- 🌐 **5 languages** - English, Spanish, French, Arabic, Dutch (100% coverage)
-- 📦 **Zero dependencies** - Lightweight and fast
-- 🔤 **ISO 3166-1 codes** - Standard country codes
-- 💪 **TypeScript** - Full type definitions included
-- ⚡ **Tree-shakeable** - Import only what you need
-- 🎯 Works with React, Angular, Vue, Svelte, Node.js, and plain JavaScript
+- 🌍 **250 countries** — Complete coverage of all world countries
+- 🏳️ **Country flags** — Flag emoji for every country
+- 🗺️ **7 continents** — All continents included
+- 🏙️ **4,010 cities** — Major cities from around the world
+- 🌐 **5 languages** — English, Spanish, French, Arabic, Dutch (100% coverage)
+- 📦 **Zero dependencies** — Lightweight and fast
+- 🔤 **ISO 3166-1 codes** — Standard alpha-2 country codes
+- 💪 **TypeScript** — Full type definitions included
+- ⚡ **Tree-shakeable** — Import only what you need
+- 🎯 **Universal** — Works with ESM and CommonJS
+
+---
 
 ## Usage
 
@@ -28,8 +45,10 @@ npm install i18n-countries-continents
 ```js
 import { getCountryName } from 'i18n-countries-continents';
 
-console.log(getCountryName('FR', 'fr')); // France
-console.log(getCountryName('FR', 'es')); // Francia
+console.log(getCountryName('FR', 'fr')); // "France"
+console.log(getCountryName('FR', 'es')); // "Francia"
+console.log(getCountryName('DE', 'ar')); // "ألمانيا"
+console.log(getCountryName('JP', 'nl')); // "Japan"
 ```
 
 ### 2. Get a country flag
@@ -40,6 +59,7 @@ import { getCountryFlag } from 'i18n-countries-continents';
 console.log(getCountryFlag('US')); // 🇺🇸
 console.log(getCountryFlag('FR')); // 🇫🇷
 console.log(getCountryFlag('JP')); // 🇯🇵
+console.log(getCountryFlag('MA')); // 🇲🇦
 ```
 
 ### 3. List all countries in a language
@@ -48,10 +68,10 @@ console.log(getCountryFlag('JP')); // 🇯🇵
 import { getCountries } from 'i18n-countries-continents';
 
 const countries = getCountries('en');
-countries.forEach(c => console.log(c.flag, c.code, c.name));
-// Output: 🇺🇸 US United States
-//         🇫🇷 FR France
-//         ...
+countries.forEach(c => console.log(c.flag, c.code, c.name, c.continent));
+// 🇺🇸 US United States NA
+// 🇫🇷 FR France EU
+// ...
 ```
 
 ### 4. Get a continent code by country code
@@ -60,6 +80,8 @@ countries.forEach(c => console.log(c.flag, c.code, c.name));
 import { getContinentByCountry } from 'i18n-countries-continents';
 
 console.log(getContinentByCountry('US')); // "NA"
+console.log(getContinentByCountry('JP')); // "AS"
+console.log(getContinentByCountry('BR')); // "SA"
 ```
 
 ### 5. Get a continent name in a specific language
@@ -67,7 +89,9 @@ console.log(getContinentByCountry('US')); // "NA"
 ```js
 import { getContinentName } from 'i18n-countries-continents';
 
-console.log(getContinentName('EU', 'es')); // Europa
+console.log(getContinentName('EU', 'es')); // "Europa"
+console.log(getContinentName('NA', 'fr')); // "Amérique du Nord"
+console.log(getContinentName('AS', 'ar')); // "آسيا"
 ```
 
 ### 6. List all continents in a language
@@ -75,8 +99,12 @@ console.log(getContinentName('EU', 'es')); // Europa
 ```js
 import { getContinents } from 'i18n-countries-continents';
 
-const continents = getContinents('fr');
+const continents = getContinents('nl');
 continents.forEach(c => console.log(c.code, c.name));
+// AF Afrika
+// AS Azië
+// EU Europa
+// ...
 ```
 
 ### 7. Get a city name in a specific language
@@ -84,9 +112,9 @@ continents.forEach(c => console.log(c.code, c.name));
 ```js
 import { getCityName } from 'i18n-countries-continents';
 
-console.log(getCityName('Paris', 'fr')); // Paris
-console.log(getCityName('Paris', 'ar')); // باريس
-console.log(getCityName('London', 'fr')); // Londres
+console.log(getCityName('Paris', 'ar'));  // "باريس"
+console.log(getCityName('London', 'fr')); // "Londres"
+console.log(getCityName('Tokyo', 'ar'));  // "طوكيو"
 ```
 
 ### 8. List all cities in a language
@@ -96,6 +124,9 @@ import { getCities } from 'i18n-countries-continents';
 
 const cities = getCities('es');
 cities.forEach(c => console.log(c.name, '→', c.translatedName));
+// Paris → París
+// London → Londres
+// ...
 ```
 
 ### 9. Search for cities
@@ -103,11 +134,8 @@ cities.forEach(c => console.log(c.name, '→', c.translatedName));
 ```js
 import { searchCities } from 'i18n-countries-continents';
 
-// Search for cities containing "york" in English
 const results = searchCities('york', 'en', 5);
 results.forEach(c => console.log(c.name, '→', c.translatedName));
-
-// Output:
 // East York → East York
 // New York → New York
 // North York → North York
@@ -121,161 +149,192 @@ results.forEach(c => console.log(c.name, '→', c.translatedName));
 ### React
 
 ```jsx
-import { getCountries } from 'i18n-countries-continents';
+import { getCountries, getCountryFlag } from 'i18n-countries-continents';
 
-function CountryList() {
+function CountrySelector() {
   const countries = getCountries('fr');
   return (
-    <ul>
-      {countries.map(c => <li key={c.code}>{c.name}</li>)}
-    </ul>
+    <select>
+      {countries.map(c => (
+        <option key={c.code} value={c.code}>
+          {c.flag} {c.name}
+        </option>
+      ))}
+    </select>
   );
 }
 ```
 
-### Angular
+### Vue
 
-```typescript
+```vue
+<script setup>
 import { getCountries } from 'i18n-countries-continents';
+const countries = getCountries('es');
+</script>
+
+<template>
+  <ul>
+    <li v-for="c in countries" :key="c.code">{{ c.flag }} {{ c.name }}</li>
+  </ul>
+</template>
+```
 
-@Component({ /* ... */ })
-export class MyComponent {
-  countries = getCountries('es');
+### Angular
+
+```typescript
+import { Component } from '@angular/core';
+import { getCountries, Country } from 'i18n-countries-continents';
+
+@Component({ selector: 'app-root', template: `
+  <li *ngFor="let c of countries">{{ c.flag }} {{ c.name }}</li>
+` })
+export class AppComponent {
+  countries: Country[] = getCountries('en');
 }
 ```
 
-### Vue
+### Node.js (ESM)
 
-```javascript
-import { getCountries } from 'i18n-countries-continents';
+```js
+import { getCountryName, getContinentByCountry, getContinentName } from 'i18n-countries-continents';
 
-export default {
-  data() {
-    return {
-      countries: getCountries('en')
-    }
-  }
-}
+const code = 'US';
+const continent = getContinentByCountry(code);          // "NA"
+const name = getContinentName(continent, 'es');          // "Norteamérica"
+console.log(`${code} is in ${name}`);
 ```
 
-### Node.js
+### Node.js (CommonJS)
 
-```javascript
-const { getContinentByCountry, getContinentName } = require('i18n-countries-continents');
+```js
+const { getCountryName, getCountryFlag, getContinentByCountry } = require('i18n-countries-continents');
 
-const continentCode = getContinentByCountry('US');
-const continentName = getContinentName(continentCode, 'es');
-console.log(continentName); // Norteamérica
+console.log(getCountryName('US', 'en'));    // "United States"
+console.log(getCountryFlag('FR'));           // 🇫🇷
+console.log(getContinentByCountry('JP'));   // "AS"
 ```
 
----
+### Sub-path imports (tree-shaking)
+
+Import individual functions for the smallest possible bundle:
+
+```js
+import getCountryName from 'i18n-countries-continents/get-country-name';
+import getCountryFlag from 'i18n-countries-continents/get-country-flag';
+import getCountries   from 'i18n-countries-continents/get-countries';
+import getContinents  from 'i18n-countries-continents/get-continents';
+import getContinentByCountry from 'i18n-countries-continents/get-continent-by-country';
+import getContinentName      from 'i18n-countries-continents/get-continent-name';
+import getCityName    from 'i18n-countries-continents/get-city-name';
+import getCities      from 'i18n-countries-continents/get-cities';
+import searchCities   from 'i18n-countries-continents/search-cities';
+```
 
 ---
 
 ## Data Coverage
 
 ### Countries: 250
-- **Africa**: 58 countries
-- **Antarctica**: 5 territories
-- **Asia**: 53 countries
-- **Europe**: 53 countries
-- **North America**: 41 countries
-- **Oceania**: 26 countries
-- **South America**: 14 countries
+| Continent | Count |
+|-----------|-------|
+| Africa | 58 countries |
+| Antarctica | 5 territories |
+| Asia | 53 countries |
+| Europe | 53 countries |
+| North America | 41 countries |
+| Oceania | 26 countries |
+| South America | 14 countries |
 
 ### Continents: 7
 All continents fully covered with translations in all 5 languages.
 
 ### Cities: 4,010
-Major cities from around the world including:
-- Capital cities
-- Major metropolitan areas
-- Important economic centers
-- Cultural landmarks
+Major cities from around the world — capital cities, major metropolitan areas, important economic centers, and cultural landmarks.
 
 ### Languages: 5
-- English (en) - 100%
-- Spanish (es) - 100%
-- French (fr) - 100%
-- Arabic (ar) - 100%
-- Dutch (nl) - 100%
+| Code | Language | Coverage |
+|------|----------|----------|
+| `en` | English  | 100% |
+| `es` | Spanish  | 100% |
+| `fr` | French   | 100% |
+| `ar` | Arabic   | 100% |
+| `nl` | Dutch    | 100% |
 
 ---
 
 ## API Reference
 
-### Country Services
+### Country Functions
 
-#### `getCountryName(code: string, language?: SupportedLanguage): string | undefined`
+#### `getCountryName(code, language?): string | undefined`
 Get the name of a country by its ISO 3166-1 alpha-2 code.
+- `code` — country code, e.g. `'US'`, `'FR'` (case-insensitive)
+- `language` — one of `'en' | 'es' | 'fr' | 'ar' | 'nl'` (default: `'en'`)
 
-#### `getCountryFlag(code: string): string | undefined`
+#### `getCountryFlag(code): string | undefined`
 Get the flag emoji for a country by its ISO 3166-1 alpha-2 code.
 
-#### `getCountries(language?: SupportedLanguage): Country[]`
-Get all countries with their names and flags in the specified language.
+#### `getCountries(language?): Country[]`
+Get all 250 countries with their names, flags, and continent codes in the specified language.
+
+#### `getContinentByCountry(code): string | undefined`
+Get the continent code for a country (e.g. `'EU'`, `'AS'`, `'NA'`).
+
+---
+
+### Continent Functions
 
-#### `getContinentByCountry(code: string): string | undefined`
-Get the continent code for a country.
+#### `getContinentName(code, language?): string | undefined`
+Get the name of a continent by its code (`'AF' | 'AN' | 'AS' | 'EU' | 'NA' | 'OC' | 'SA'`).
 
-### Continent Services
+#### `getContinents(language?): Continent[]`
+Get all 7 continents with their names in the specified language.
 
-#### `getContinentName(code: string, language?: SupportedLanguage): string | undefined`
-Get the name of a continent by its code.
+---
 
-#### `getContinents(language?: SupportedLanguage): Continent[]`
-Get all continents with their names in the specified language.
+### City Functions
 
-### City Services
+#### `getCityName(cityName, language?): string | undefined`
+Get the translated name of a city by its English name.
 
-#### `getCityName(cityName: string, language?: SupportedLanguage): string | undefined`
-Get the translated name of a city.
+#### `getCities(language?): City[]`
+Get all 4,010 cities with their translated names in the specified language.
 
-#### `getCities(language?: SupportedLanguage): City[]`
-Get all cities with their names in the specified language.
+#### `searchCities(query, language?, limit?): City[]`
+Search for cities by name (searches both English and translated names).
+- `limit` — max results to return (default: `10`)
 
-#### `searchCities(query: string, language?: SupportedLanguage, limit?: number): City[]`
-Search for cities by name. Returns up to `limit` results (default: 10).
+---
 
-### Types
+### Constants & Types
 
 ```typescript
+import { SUPPORTED_LANGUAGES } from 'i18n-countries-continents';
+// ['en', 'es', 'fr', 'ar', 'nl']
+
 type SupportedLanguage = 'en' | 'es' | 'fr' | 'ar' | 'nl';
 
 interface Country {
-  code: string;
-  continent: string;
-  name: string;
-  flag: string;
+  code: string;      // ISO 3166-1 alpha-2, e.g. "US"
+  continent: string; // e.g. "NA"
+  name: string;      // translated name
+  flag: string;      // emoji, e.g. "🇺🇸"
 }
 
 interface Continent {
-  code: string;
-  name: string;
+  code: string; // e.g. "EU"
+  name: string; // translated name
 }
 
 interface City {
-  name: string;
-  translatedName: string;
+  name: string;           // English name
+  translatedName: string; // translated name
 }
 ```
 
 ---
 
-## Data Format
-
-Country, continent, and city data is stored in JSON format in `src/data/` directory. This makes it easy to:
-- Add new data or translations
-- Update existing data
-- Contribute via pull requests
-- Parse and validate programmatically
-
----
-
----
-
 ## License
 
-MIT
-
----
+MIT © [Aissam EL Houref](https://github.com/ElhourefAissam)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "i18n-countries-continents",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "description": "Get country, continent, and city names in different languages. 250 countries, 7 continents, and 4,010 cities with 5 languages. Works in React, Angular, Vue, Node.js, and any JavaScript environment.",
   "type": "module",
   "main": "dist/index.js",