{"id":50771185,"url":"https://github.com/yusifaliyevpro/countries","last_synced_at":"2026-06-11T19:00:26.406Z","repository":{"id":281715826,"uuid":"946188395","full_name":"yusifaliyevpro/countries","owner":"yusifaliyevpro","description":"TypeScript wrapper for Rest Countries API to fetch country data by codes, capitals, or all countries with full typings.","archived":false,"fork":false,"pushed_at":"2026-06-11T17:54:51.000Z","size":460,"stargazers_count":19,"open_issues_count":1,"forks_count":4,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-06-11T18:17:38.747Z","etag":null,"topics":["countries","countries-api","typed-countries","types-countries"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/@yusifaliyevpro/countries","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/yusifaliyevpro.png","metadata":{"files":{"readme":"README.MD","changelog":null,"contributing":null,"funding":".github/FUNDING.YML","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"patreon":"yusifaliyevpro"}},"created_at":"2025-03-10T18:46:56.000Z","updated_at":"2026-06-11T17:54:14.000Z","dependencies_parsed_at":null,"dependency_job_id":"c5836289-fe71-40cd-881d-50605dc0838e","html_url":"https://github.com/yusifaliyevpro/countries","commit_stats":null,"previous_names":["yusifaliyevpro/countries"],"tags_count":24,"template":false,"template_full_name":null,"purl":"pkg:github/yusifaliyevpro/countries","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yusifaliyevpro%2Fcountries","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yusifaliyevpro%2Fcountries/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yusifaliyevpro%2Fcountries/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yusifaliyevpro%2Fcountries/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/yusifaliyevpro","download_url":"https://codeload.github.com/yusifaliyevpro/countries/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yusifaliyevpro%2Fcountries/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34213179,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-11T02:00:06.485Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["countries","countries-api","typed-countries","types-countries"],"created_at":"2026-06-11T19:00:16.859Z","updated_at":"2026-06-11T19:00:26.384Z","avatar_url":"https://github.com/yusifaliyevpro.png","language":"TypeScript","funding_links":["https://patreon.com/yusifaliyevpro"],"categories":[],"sub_categories":[],"readme":"# REST Countries Typed API Package 🇦🇿 🇵🇪\n\nThis package provides an easy and `TYPE-SAFE` way to interact with the [REST Countries API](https://restcountries.com/), which offers detailed information about countries worldwide. You can fetch country data using various parameters like alpha-2/alpha-3/CIOC/CCN3 codes, capital cities, languages, regions, subregions, translations, demonyms and currencies. `Thanks to Alejandro Matos for this API.`\n\n\u003e ## ⚠️ v5 — Breaking changes (REST Countries v5)\n\u003e\n\u003e REST Countries shut down v1–v4 and now only serves **v5**, which **requires an API key** and **completely restructured the response schema**. This package's v5 is a ground-up rewrite to match (the major version now tracks the API version):\n\u003e\n\u003e - **API key is now required.** [Sign up here](https://restcountries.com/sign-up) to get one.\n\u003e - **New class-based API.** Instead of importing standalone functions, you create one `RestCountries` instance with your key and call methods on it.\n\u003e - **New data shape.** e.g. `name` → `names`, `cca2`/`cca3` → `codes.alpha_2`/`codes.alpha_3`, `capital: string[]` → `capitals: { name, coordinates, attributes }[]`. See [Available Fields](#available-fields).\n\u003e - **Pagination.** List methods now return `{ countries, meta }` and accept `limit`/`offset`.\n\u003e - **New capabilities.** Free-text [`search()`](#search) and composable [`filters`](#filtering) (memberships, classification, landlocked, continent…).\n\u003e\n\u003e Migrating from v2.x? See the [field map](#migrating-from-v2x-field-map) for the old→new property translations. If you're not ready to migrate, pin `@yusifaliyevpro/countries@2`.\n\n## Installation\n\n```bash\nnpm install @yusifaliyevpro/countries\n```\n\n## Getting started\n\nCreate a single client with your API key and reuse it everywhere:\n\n```typescript\nimport { RestCountries } from \"@yusifaliyevpro/countries\";\n\nconst restCountries = new RestCountries({ apiKey: process.env.REST_COUNTRIES_API_KEY! });\n\n// Fetch a single country\nconst canada = await restCountries.getCountryByCode({\n  code: \"CAN\",\n  fields: [\"names\", \"capitals\", \"flag\"],\n});\n\n// Fetch a paginated list\nconst { countries, meta } = await restCountries.getCountriesByRegion({\n  region: \"Europe\",\n  fields: [\"names\", \"population\"],\n  limit: 10,\n});\n```\n\n\u003e **Keep your API key secret.** Load it from an environment variable (e.g. `.env`) — never commit it.\n\n### Client options\n\n```typescript\nnew RestCountries({\n  apiKey: \"rc_live_...\", // required — sent as `Authorization: Bearer \u003capiKey\u003e`\n  baseURL: \"https://...\", // optional — override the API base URL\n  fetch: customFetch, // optional — custom fetch implementation\n});\n```\n\n**`Note:`** If you don't set the `fields` parameter, all data will be fetched.\n\n---\n\n## Migrating from v2.x (field map)\n\nv5 restructured the schema. Use this table to translate the `fields` you used to request and the properties you read off each country. Because `fields` selects at **top-level key granularity**, the \"Request field\" column is what you pass to `fields`; the \"Read it as\" column is the property path on the returned object.\n\n| v2 field                  | Request field (v5) | Read it as (v5)                           | Notes                                            |\n| ------------------------- | ------------------ | ----------------------------------------- | ------------------------------------------------ |\n| `name`                    | `names`            | `names.common`, `names.official`          |                                                  |\n| `name.nativeName`         | `names`            | `names.native`                            | keyed by language code                           |\n| `altSpellings`            | `names`            | `names.alternates`                        |                                                  |\n| `translations`            | `names`            | `names.translations`                      |                                                  |\n| `cca2`                    | `codes`            | `codes.alpha_2`                           |                                                  |\n| `cca3`                    | `codes`            | `codes.alpha_3`                           |                                                  |\n| `ccn3`                    | `codes`            | `codes.ccn3`                              |                                                  |\n| `cioc`                    | `codes`            | `codes.cioc`                              |                                                  |\n| `fifa`                    | `codes`            | `codes.fifa`                              |                                                  |\n| `capital`                 | `capitals`         | `capitals[].name`                         | now objects: `{ name, coordinates, attributes }` |\n| `capitalInfo.latlng`      | `capitals`         | `capitals[].coordinates`                  | `{ lat, lng }`                                   |\n| `latlng`                  | `coordinates`      | `coordinates.lat`, `coordinates.lng`      | tuple → object                                   |\n| `region`                  | `region`           | `region`                                  | unchanged                                        |\n| `subregion`               | `subregion`        | `subregion`                               | unchanged                                        |\n| `continents`              | `continents`       | `continents`                              | unchanged                                        |\n| `borders`                 | `borders`          | `borders`                                 | unchanged                                        |\n| `landlocked`              | `landlocked`       | `landlocked`                              | unchanged                                        |\n| `area`                    | `area`             | `area.kilometers`, `area.miles`           | number → object                                  |\n| `population`              | `population`       | `population`                              | unchanged                                        |\n| `timezones`               | `timezones`        | `timezones`                               | unchanged                                        |\n| `independent`             | `classification`   | `classification.sovereign`                | closest match; see note below                    |\n| `unMember`                | `classification`   | `classification.un_member`                |                                                  |\n| `status`                  | `classification`   | `classification.iso_status`               | e.g. `\"official\"`                                |\n| `currencies`              | `currencies`       | `currencies[]`                            | `Record` → array of `{ code, name, symbol }`     |\n| `languages`               | `languages`        | `languages[].name`                        | `Record` → array of language objects             |\n| `demonyms`                | `demonyms`         | `demonyms`                                | shape unchanged (`{ [lang]: { f, m } }`)         |\n| `car.side`                | `cars`             | `cars.driving_side`                       | renamed                                          |\n| `car.signs`               | `cars`             | `cars.signs`                              |                                                  |\n| `tld`                     | `tlds`             | `tlds`                                    | renamed                                          |\n| `idd`                     | `calling_codes`    | `calling_codes`                           | `{ root, suffixes }` → `string[]`                |\n| `flag` (emoji)            | `flag`             | `flag.emoji`                              | `flag` is now an object                          |\n| `flags.png` / `flags.svg` | `flag`             | `flag.url_png`, `flag.url_svg`            |                                                  |\n| `flags.alt`               | `flag`             | `flag.description`                        |                                                  |\n| `maps.googleMaps`         | `links`            | `links.google_maps`                       |                                                  |\n| `maps.openStreetMaps`     | `links`            | `links.open_street_maps`                  |                                                  |\n| `gini`                    | `economy`          | `economy.gini_coefficient`                |                                                  |\n| `startOfWeek`             | `date`             | `date.start_of_week`                      |                                                  |\n| `postalCode`              | `postal_code`      | `postal_code.format`, `postal_code.regex` | renamed                                          |\n\n### ❌ Removed in v5 (no equivalent)\n\n- **`coatOfArms`** — coat-of-arms images are no longer provided by the API.\n\n### 🆕 New in v5\n\nFields with no v2 counterpart: `memberships` (eu, nato, un, schengen, g7, g20, brics, opec, oecd, …), `classification.dependency` / `disputed` / `un_observer`, `codes.fips` / `gec`, `government_type`, `number_format`, `parent`, `uuid`, `date.academic_year_start` / `fiscal_year_start`, `flag.unicode` / `html_entity`, and `capitals[].attributes`.\n\n\u003e **Note on `independent`:** v5 has no exact `independent` flag. `classification.sovereign` is the closest, but it isn't a 1:1 semantic match — if you relied on the old behaviour, also check `classification.dependency` and `classification.un_member`.\n\n---\n\n## Methods\n\nMethods that return **lists** resolve to `{ countries, meta } | null` and accept `limit`/`offset`.\nMethods that return a **single** country resolve to `Country | null`.\n\n| Method                                                | Returns |\n| ----------------------------------------------------- | ------- |\n| [`getCountries`](#getcountries)                       | list    |\n| [`search`](#search)                                   | list    |\n| [`getCountriesByName`](#getcountriesbyname)           | list    |\n| [`getCountriesByRegion`](#getcountriesbyregion)       | list    |\n| [`getCountriesBySubregion`](#getcountriesbysubregion) | list    |\n| [`getCountriesByLang`](#getcountriesbylang)           | list    |\n| [`getCountriesByCurrency`](#getcountriesbycurrency)   | list    |\n| [`getCountryByCode`](#getcountrybycode)               | single  |\n| [`getCountryByCapital`](#getcountrybycapital)         | single  |\n| [`getCountryByTranslation`](#getcountrybytranslation) | single  |\n| [`getCountryByDemonym`](#getcountrybydemonym)         | single  |\n\nAdditional information:\n\n- [**`Migrating from v2.x (field map)`**](#migrating-from-v2x-field-map)\n- [**`Filtering (CountryFilters)`**](#filtering)\n- [**`Pagination`**](#pagination)\n- [**`Selecting fields (fields / omitFields)`**](#available-fields)\n- [**`defineFields function`**](#definefields)\n- [**`CountryPicker Type`**](#countrypickertypeof-fields)\n- [**`Response validation (countrySchema)`**](#response-validation)\n- [**`Fetch Options`**](#fetch-options)\n- [**`Type Definitions \u0026\u0026 Available Types`**](#type-definitions)\n- [**`Available Fields`**](#available-fields)\n- [**`Error handling`**](#error-handling)\n\n---\n\n### `getCountries`\n\nFetches countries, optionally narrowed by composable [`filters`](#filtering) and/or a free-text `q`, with pagination. With no arguments it lists all countries (paginated).\n\n#### Parameters:\n\n- `filters` (optional): Composable property filters, AND-combined. See [Filtering](#filtering).\n- `q` (optional): Free-text search across all searchable properties.\n- `fields` / `omitFields` (optional): Field selection. See [Available Fields](#available-fields).\n- `limit` / `offset` (optional): Pagination (see [Pagination](#pagination)).\n\n#### Example:\n\n```typescript\n// All countries, a page at a time\nconst { countries, meta } = await restCountries.getCountries({\n  fields: [\"names\", \"capitals\"],\n  limit: 50,\n});\n\n// Landlocked EU members in Europe (filters are AND-combined)\nconst { countries } = await restCountries.getCountries({\n  filters: { region: \"Europe\", landlocked: true, memberships: { eu: true } },\n  fields: [\"names\"],\n});\n\n// Sovereign UN members\nconst { countries } = await restCountries.getCountries({\n  filters: { classification: { sovereign: true, un_member: true } },\n  fields: [\"names\"],\n});\n```\n\n---\n\n### `search`\n\nFree-text search across all searchable properties (the v5 `?q=` endpoint). Optionally narrowed by [`filters`](#filtering).\n\n#### Parameters:\n\n- `q`: The search term (first positional argument).\n- `filters` (optional): Composable property filters, AND-combined. See [Filtering](#filtering).\n- `fields` / `omitFields` (optional): Field selection.\n- `limit` / `offset` (optional): Pagination.\n\n#### Example:\n\n```typescript\nconst { countries } = await restCountries.search(\"canada\", { fields: [\"names\"] });\n\n// Combine free-text with a filter\nconst { countries } = await restCountries.search(\"island\", {\n  filters: { region: \"Oceania\" },\n  fields: [\"names\"],\n});\n```\n\n---\n\n### `getCountriesByName`\n\nFetches countries matching a name. Searches common, official, alternate and native names. Set `fullText` to require an exact common-name match.\n\n#### Parameters:\n\n- `name`: Search by country name (case-insensitive).\n- `fullText` (optional): Require an exact common-name match (default: false).\n- `fields` (optional): Array of fields to retrieve.\n- `limit` / `offset` (optional): Pagination.\n\n#### Example:\n\n```typescript\n// Partial match\nconst { countries } = await restCountries.getCountriesByName({\n  name: \"united\",\n  fields: [\"names\", \"capitals\"],\n});\n\n// Exact match\nconst { countries } = await restCountries.getCountriesByName({\n  name: \"Finland\",\n  fullText: true,\n  fields: [\"names\"],\n});\n```\n\n---\n\n### `getCountriesByRegion`\n\nFetches countries by region name.\n\n#### Parameters:\n\n- `region`: Name of the region (autocomplete).\n- `fields` (optional): Array of fields to retrieve.\n- `limit` / `offset` (optional): Pagination.\n\n#### Example:\n\n```typescript\nconst { countries } = await restCountries.getCountriesByRegion({\n  region: \"Americas\",\n});\n```\n\n---\n\n### `getCountriesBySubregion`\n\nFetches countries by subregion name.\n\n#### Parameters:\n\n- `subregion`: Name of the subregion (autocomplete).\n- `fields` (optional): Array of fields to retrieve.\n- `limit` / `offset` (optional): Pagination.\n\n#### Example:\n\n```typescript\nconst { countries } = await restCountries.getCountriesBySubregion({\n  subregion: \"Northern Europe\",\n  fields: [\"capitals\", \"area\", \"population\"],\n});\n```\n\n---\n\n### `getCountriesByLang`\n\nFetches countries where the given language is spoken (matches by language name).\n\n#### Parameters:\n\n- `lang`: Language name (autocomplete).\n- `fields` (optional): Array of fields to retrieve.\n- `limit` / `offset` (optional): Pagination.\n\n#### Example:\n\n```typescript\nconst { countries } = await restCountries.getCountriesByLang({\n  lang: \"Spanish\",\n});\n```\n\n---\n\n### `getCountriesByCurrency`\n\nFetches countries that use the given currency (matches by currency code or name).\n\n#### Parameters:\n\n- `currency`: Currency code (e.g. `\"EUR\"`) or name (e.g. `\"Euro\"`) (autocomplete).\n- `fields` (optional): Array of fields to retrieve.\n- `limit` / `offset` (optional): Pagination.\n\n#### Example:\n\n```typescript\nconst { countries } = await restCountries.getCountriesByCurrency({\n  currency: \"EUR\",\n  fields: [\"cars\", \"capitals\", \"codes\"],\n});\n```\n\n---\n\n### `getCountryByCode`\n\nFetches a single country by its code. Detects the code type (alpha-2, alpha-3, CCN3) and falls back to CIOC for three-letter codes.\n\n#### Parameters:\n\n- `code`: An alpha-3, alpha-2, CCN3 or CIOC code (case-insensitive) (autocomplete).\n- `fields` (optional): Array of fields to retrieve.\n\n#### Example:\n\n```typescript\nconst azerbaijan = await restCountries.getCountryByCode({ code: \"AZE\" });\n\nconst switzerland = await restCountries.getCountryByCode({\n  code: \"SUI\", // CIOC code — resolved via fallback\n  fields: [\"names\", \"codes\", \"population\"],\n});\n```\n\n---\n\n### `getCountryByCapital`\n\nFetches a single country by its capital city.\n\n#### Parameters:\n\n- `capital`: Capital city name (case-insensitive) (autocomplete).\n- `fields` (optional): Array of fields to retrieve.\n\n#### Example:\n\n```typescript\nconst germany = await restCountries.getCountryByCapital({\n  capital: \"Berlin\",\n  fields: [\"names\", \"flag\", \"currencies\"],\n});\n```\n\n---\n\n### `getCountryByTranslation`\n\nFetches a single country by a translated name.\n\n#### Parameters:\n\n- `translation`: A translated country name (case-insensitive).\n- `fields` (optional): Array of fields to retrieve.\n\n#### Example:\n\n```typescript\nconst germany = await restCountries.getCountryByTranslation({\n  translation: \"Deutschland\",\n  fields: [\"cars\", \"capitals\", \"codes\"],\n});\n```\n\n---\n\n### `getCountryByDemonym`\n\nFetches a single country by its demonym.\n\n#### Parameters:\n\n- `demonym`: A demonym (case-insensitive).\n- `fields` (optional): Array of fields to retrieve.\n\n#### Example:\n\n```typescript\nconst peru = await restCountries.getCountryByDemonym({\n  demonym: \"Peruvian\",\n  fields: [\"cars\", \"capitals\", \"codes\"],\n});\n```\n\n---\n\n## Filtering\n\n`getCountries` and `search` accept a typed `filters` object (`CountryFilters`). Every provided filter is **AND-combined**, so you can compose them freely:\n\n```typescript\nconst { countries } = await restCountries.getCountries({\n  filters: {\n    region: \"Europe\", // region name\n    subregion: \"Western Europe\", // subregion name\n    continent: \"Europe\", // matches countries whose `continents` include this\n    landlocked: true,\n    classification: { sovereign: true, un_member: true, disputed: false },\n    memberships: { eu: true, nato: true, schengen: true }, // eu, nato, un, g7, g20, brics, opec, oecd, ...\n  },\n  fields: [\"names\"],\n});\n```\n\nAll filter keys are optional and fully typed. `classification` and `memberships` expose every boolean flag from those objects on `Country`.\n\n---\n\n## Pagination\n\nREST Countries v5 paginates results (default 25 per page, max 100). List methods expose `limit` and `offset` and return a `meta` object describing the current page:\n\n```typescript\nconst { countries, meta } = await restCountries.getCountriesByRegion({\n  region: \"Africa\",\n  fields: [\"names\"],\n  limit: 100,\n  offset: 0,\n});\n\n// meta: { total, count, limit, offset, more, request_id, duration }\nif (meta.more) {\n  const next = await restCountries.getCountriesByRegion({\n    region: \"Africa\",\n    fields: [\"names\"],\n    limit: 100,\n    offset: meta.offset + meta.limit,\n  });\n}\n```\n\n---\n\n## Fetch Options\n\nEvery method accepts an optional second argument with any valid `fetch` options (custom headers, caching, timeouts, etc.). The `Authorization` header is added automatically; anything you pass is merged on top.\n\n```typescript\n// Next.js caching example\nconst germany = await restCountries.getCountryByCode(\n  { code: \"DEU\", fields: [\"names\", \"capitals\"] },\n  { next: { revalidate: 7 * 24 * 3600 }, cache: \"force-cache\" },\n);\n```\n\n---\n\n## Available Fields\n\nThe `fields` parameter selects **top-level** properties of `Country` and gives autocomplete suggestions. Full list:\n\n- `names`: common, official, alternates, native and translations\n- `codes`: alpha_2, alpha_3, ccn3, cioc, fifa, fips, gec\n- `capitals`: array of `{ name, coordinates, attributes }`\n- `flag`: description, emoji, html_entity, unicode, url_png, url_svg\n- `region`, `subregion`\n- `area`: `{ kilometers, miles }`\n- `borders`, `calling_codes`, `continents`, `timezones`, `tlds`, `assets`\n- `cars`: `{ driving_side, signs }`\n- `classification`: sovereign, un_member, un_observer, dependency, disputed, iso_status\n- `coordinates`: `{ lat, lng }`\n- `currencies`: array of `{ code, name, symbol }`\n- `date`: academic / fiscal year start, start_of_week\n- `demonyms`: per-language `{ f, m }`\n- `economy`: gini_coefficient\n- `government_type`, `landlocked`, `population`\n- `languages`: array of language objects\n- `leaders`: (paid plans only)\n- `links`: official, wikipedia, google_maps, open_street_maps\n- `memberships`: un, eu, nato, oecd, g7, g20, brics, opec, schengen, …\n- `number_format`: decimal/thousands separators\n- `parent`: `{ alpha_2, alpha_3 }`\n- `postal_code`: `{ format, regex }`\n- `uuid`\n\n\u003e **Note:** `fields` selects at top-level key granularity. Requesting `[\"names\"]` returns the whole `names` object.\n\n### `omitFields` — fetch everything except some fields\n\nEvery method also accepts `omitFields` (maps to v5 `response_fields_omit`) to fetch all fields _except_ the listed ones — handy for dropping heavy fields like `names.translations` or `leaders`:\n\n```typescript\n// Everything except translations and leaders\nconst { countries } = await restCountries.getCountries({ omitFields: [\"leaders\"], limit: 10 });\n```\n\n\u003e **Note:** `omitFields` is applied at runtime only; it does not narrow the return type (you still get the full `Country` type). Use `fields` when you want the type narrowed.\n\n```typescript\nconst country = await restCountries.getCountryByCode({\n  code: \"TUR\",\n  fields: [\"names\", \"capitals\", \"population\"],\n});\n```\n\n---\n\n## Type Definitions\n\nThis package exports TypeScript type definitions. Import them from the main entry or the `/types` subpath:\n\n```typescript\nimport type { Country, Region, Cca2Code } from \"@yusifaliyevpro/countries/types\";\n```\n\n## Available Types\n\n**`Note:` If a long time has passed since the last update, the type data may be outdated.**\n\n- **`Country`**: Comprehensive type for a v5 country object.\n- **`CountryList`**: `{ countries: CountryPicker\u003cT\u003e[]; meta: ResponseMeta }` returned by list methods.\n- **`ResponseMeta`**: Pagination metadata (`total`, `count`, `limit`, `offset`, `more`, `request_id`, `duration`).\n- **`CountryPicker`**: Picks the requested top-level fields from `Country`.\n- **`CountryFilters`**: Typed, composable filters for `getCountries` / `search`.\n- **`RestCountriesConfig`**: Options for the `RestCountries` constructor.\n- **`Cca2Code` / `Cca3Code` / `Ccn3Code` / `CiocCode`**: Country codes (accept any string ✅).\n- **`Capital`**: Capital city names (accept any string ✅).\n- **`Region`**: World regions (e.g., \"Africa\", \"Americas\").\n- **`Subregion`**: World subregions (accept any string ✅).\n- **`Lang`**: Language names (accept any string ✅).\n- **`Currency`**: Currency codes (accept any string ✅).\n- **`SupportedLanguages`**: Languages supported for translations.\n\n---\n\n## Response validation\n\nThe `Country` type is **inferred from a [Zod Mini](https://zod.dev/packages/mini) schema** (`countrySchema`), which is exported so you can validate responses at runtime if you want:\n\n```typescript\nimport { countrySchema } from \"@yusifaliyevpro/countries\";\n\nconst country = await restCountries.getCountryByCode({ code: \"CAN\" });\nconst result = countrySchema.safeParse(country);\nif (!result.success) console.error(result.error.issues);\n```\n\nZod Mini is used to keep the footprint small, and the schema is only pulled into your bundle if you actually import `countrySchema` (the package is marked side-effect-free).\n\n---\n\n## `defineFields`\n\n`defineFields` lets you define a fields array **with autocomplete and type checking** outside of a call site, preserving the literal tuple type so `CountryPicker` can narrow correctly.\n\n```typescript\nimport { defineFields } from \"@yusifaliyevpro/countries\";\n\nconst countryFields = defineFields([\"names\", \"capitals\", \"population\", \"region\", \"codes\", \"flag\"]);\n\nconst country = await restCountries.getCountryByCode({ code: \"DEU\", fields: countryFields });\n```\n\n---\n\n## `CountryPicker\u003ctypeof fields\u003e`\n\n`CountryPicker` is a generic type that takes the `fields` array and returns a country type containing only those fields.\n\n### ⚡ Example Full Usage\n\n```tsx\n// src/lib/fields.ts\nexport const countryFields = defineFields([\"names\", \"capitals\", \"population\", \"region\"]);\n\n// src/app/page.tsx\nexport default async function CountryPage() {\n  const country = await restCountries.getCountryByCode({ code: \"AZ\", fields: countryFields });\n  return (\n    \u003cmain\u003e\n      \u003cCountryCard country={country} /\u003e\n    \u003c/main\u003e\n  );\n}\n\n// src/components/CountryCard.tsx\nexport function CountryCard({ country }: { country: CountryPicker\u003ctypeof countryFields\u003e }) {\n  return \u003cdiv\u003e{country.names.common}\u003c/div\u003e;\n}\n```\n\n### ✅ Benefits\n\n- **No need for manual type definition** for the returned country.\n- **Type-safe fields**: autocomplete and error checking.\n- **Reusability**: use the same `fields` and type across your app.\n- Prevents accessing fields you didn't fetch.\n\n---\n\n## Error Handling\n\nErrors are handled gracefully and logged to the console. On a not-found, network, or authentication error the method resolves to `null` (single) or an empty page / `null` (lists).\n\n```typescript\nconst data = await restCountries.getCountryByCode({\n  code: \"XXX\",\n  fields: [\"names\"],\n}); // null, with an error logged by the library\n\nconst usa = await restCountries.getCountryByCode({\n  code: \"USA\",\n  fields: [\"names\", \"population\"],\n});\n\n// TypeScript Error — 'capitals' was not requested in fields\nconsole.log(usa.capitals);\n                ^^^^^^^^\n```\n\n---\n\n## License\n\nMIT License.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyusifaliyevpro%2Fcountries","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyusifaliyevpro%2Fcountries","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyusifaliyevpro%2Fcountries/lists"}