🌐 WorldKit Core (@worldkit/core)

One global toolkit for JavaScript, TypeScript, React, Cloudflare Workers, and Node.js.

WorldKit is the modern, ultra-fast global data toolkit. It provides instant $O(1)$ lookups for countries, currencies, cities, states, timezones, languages, flags, E.164 phone formatting & validation, EU VAT checks, postal codes, and a sub-3ms multi-entity search engine.

📚 Full Documentation & Interactive Playground: https://worldkit.in/docs/packages/core

⚡ Why WorldKit?

• 🚀 Ultra Fast ($O(1)$): Zero API latency. All queries run in-memory (<0.01ms).
• 📦 Modular & Tree-Shakeable: Use the full unified @worldkit/core facade or pick tiny single-purpose packages.
• 🛡️ 100% Edge Compatible: Built with zero Node.js native dependencies (fs, net). Compatible out-of-the-box with Cloudflare Workers, Vercel Edge, Deno, and Bun.
• 📐 100% TypeScript: Built with strict types and full autocompletion.

📦 Install

npm install @worldkit/core
# or
pnpm add @worldkit/core
# or
yarn add @worldkit/core

💡 Usage

import { world } from "@worldkit/core";

// 1. Country Lookups (O(1) Hash Map)
const japan = world.country("JP");
console.log(japan?.name, japan?.emoji, japan?.currency); // "Japan", "🇯🇵", "JPY"

// 2. Currency Details & Symbols
const euro = world.currency("EUR");
console.log(euro?.symbol); // "€"

// 3. States & Cities
const caStates = world.states("CA"); // Ontario, Quebec, etc.
const usCities = world.cities("US"); // New York, Los Angeles, etc.

// 4. Timezones & UTC Offsets
console.log(world.timezones("IN")); // ["Asia/Kolkata"]
console.log(world.utcOffset("Asia/Kolkata")); // "+05:30"

// 5. Multi-Entity Search Engine (<3ms)
const searchResults = world.search("Tokyo");

// 6. E.164 Phone Validation & Formatting
console.log(world.validatePhone("+14155552671", "US")); // true
console.log(world.formatPhone("9876543210", "IN")); // "+91 98765 43210"

// 7. EU VAT Verification
console.log(world.validateVat("DE123456789")); // true

⚡ Cloudflare Workers Example

import { country, currency, validatePhone, formatPhone } from "@worldkit/core";

export default {
  async fetch(request: Request): Promise<Response> {
    const cfCountry = (request.cf?.country as string) || "US";

    const countryData = country(cfCountry);
    const currencyData = countryData ? currency(countryData.currency) : null;

    return Response.json({
      success: true,
      edgeRegion: cfCountry,
      country: countryData?.name,
      currency: currencyData?.symbol,
      flag: countryData?.emoji,
    });
  },
};

🧩 Modular Package Ecosystem

WorldKit is built as a monorepo of tree-shakeable micro-packages:

| Package | Purpose | Docs Link | | :--- | :--- | :--- | | @worldkit/countries | 250+ countries dataset & ISO2/ISO3 lookup | Docs | | @worldkit/currencies | 160+ ISO-4217 currencies & symbols | Docs | | @worldkit/cities | World cities filtered by country | Docs | | @worldkit/states | 4,000+ states, provinces & subdivisions | Docs | | @worldkit/phone | E.164 phone formatting & validation | Docs | | @worldkit/timezone | 400+ timezones with UTC offsets | Docs | | @worldkit/languages | ISO 639-1 languages dataset | Docs | | @worldkit/flags | Unicode flag emojis & SVG flag helpers | Docs | | @worldkit/validators | Phone, EU VAT & postal validators | Docs | | @worldkit/formatters | Currency, address & phone formatters | Docs | | @worldkit/postal | Postal code format regexes | Docs | | @worldkit/search | Multi-entity fuzzy search (<3ms) | Docs | | @worldkit/react | React select dropdown components | Docs | | @worldkit/cli | Terminal CLI search utility | Docs |

📜 License

MIT © WorldKit