🌐 WorldKit Global Data Toolkit

WorldKit is the modern, ultra-fast, zero-dependency global data toolkit for JavaScript, TypeScript, Cloudflare Workers, Edge Runtimes, React, and Node.js.

It provides instant $O(1)$ lookups for countries, currencies, cities, states/subdivisions, timezones, languages, flags, E.164 phone formatting & validation, EU VAT verification, postal code regexes, and a unified multi-entity search engine (< 3ms).

📚 Full Documentation: https://worldkit.in

---

📦 Ecosystem Packages

Every package in WorldKit is designed to be standalone, tree-shakeable, and independently installable:

Package	Version	Description	Package README	Full Docs
@worldkit/core	1.0.3	Unified facade for all WorldKit functions	README	Docs
@worldkit/countries	1.0.3	250+ Countries & Territories with ISO2/ISO3 lookups	README	Docs
@worldkit/currencies	1.0.3	160+ ISO-4217 Currencies with symbols & country mapping	README	Docs
@worldkit/cities	1.0.3	Major world cities filtered by country ISO2	README	Docs
@worldkit/states	1.0.3	4,000+ States, Provinces & Subdivisions	README	Docs
@worldkit/timezone	1.0.3	400+ Timezones with UTC offsets	README	Docs
@worldkit/languages	1.0.3	180+ ISO 639-1 languages with native names	README	Docs
@worldkit/phone	1.0.3	E.164 dial codes & length validation rules	README	Docs
@worldkit/postal	1.0.3	Postal code regex patterns by country	README	Docs
@worldkit/validators	1.0.3	Phone, EU VAT, Postal Code, Country & Currency validators	README	Docs
@worldkit/formatters	1.0.3	Currency, Address, and E.164 Phone formatters	README	Docs
@worldkit/flags	1.0.3	Emoji flags & SVG flag helpers	README	Docs
@worldkit/search	1.0.3	Unified multi-entity search engine (< 3ms)	README	Docs
@worldkit/react	1.0.3	React select components & Documentation Tab layout	README	Docs
@worldkit/cli	1.0.3	Command line search & lookup utility	README	Docs
@worldkit/data	1.0.3	Core compiled immutable JSON datasets	README	Docs

---

⚡ Cloudflare Workers & Edge Runtimes

WorldKit has zero node-native dependencies (fs, net, path). It relies purely on ES modules and standard JS objects, making it 100% compatible out-of-the-box with Cloudflare Workers, Vercel Edge Functions, Deno, Bun, and AWS Lambda@Edge.

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;

    const inputPhone = "+819012345678";
    const isValidPhone = validatePhone(inputPhone, cfCountry);
    const formattedPhone = formatPhone(inputPhone, cfCountry);

    return Response.json({
      success: true,
      edgeRegion: cfCountry,
      country: {
        name: countryData?.name,
        emojiFlag: countryData?.emoji,
        capital: countryData?.capital,
        phoneCode: `+${countryData?.phone}`,
      },
      currency: {
        code: currencyData?.code,
        name: currencyData?.name,
        symbol: currencyData?.symbol,
      },
      phone: {
        valid: isValidPhone,
        e164: formattedPhone,
      },
      executionTimeMs: "< 0.05ms",
    });
  },
};

---

🚀 Quickstart & Installation

# Install full suite
npm install @worldkit/core

# Or install specific tree-shakeable packages
npm install @worldkit/countries @worldkit/currencies @worldkit/react

Core API Examples (@worldkit/core)

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

// Country lookups (O(1) Hash Map)
const japan = world.country("JP");

// Currency lookups
const usd = world.currency("USD");

// States & Cities
const caStates = world.states("CA");
const usCities = world.cities("US");

// Multi-entity search engine
const searchResults = world.search("Tokyo");

// E.164 Phone validation & formatting
const isValid = world.validatePhone("+14155552671", "US");
const formatted = world.formatPhone("9876543210", "IN");

// EU VAT Verification
const isVatValid = world.validateVat("DE123456789");

---

⚛️ React Components (@worldkit/react)

import React, { useState } from "react";
import { CountrySelect, StateSelect, CitySelect, CurrencySelect } from "@worldkit/react";

export function UserRegistrationForm() {
  const [country, setCountry] = useState("US");
  const [state, setState] = useState("CA");

  return (
    <form className="space-y-4">
      <CountrySelect
        value={country}
        onChange={(e) => setCountry(e.target.value)}
        showFlag={true}
      />

      <StateSelect
        countryIso2={country}
        value={state}
        onChange={(e) => setState(e.target.value)}
      />

      <CurrencySelect placeholder="Preferred Currency" />
    </form>
  );
}

---

💻 CLI Toolkit (@worldkit/cli)

Run instant global queries right from your terminal without installing anything:

# Search across countries, currencies, and cities
npx @worldkit/cli search Japan

# Inspect country details
npx @worldkit/cli info DE

# List all supported currencies
npx @worldkit/cli currencies

# Validate phone number
npx @worldkit/cli validate-phone +919876543210 IN

---

📊 Performance & Benchmarks

Operation	WorldKit (@worldkit)	Traditional Libraries	Speedup
Country ISO Lookup	0.004 ms	0.42 ms (i18n-iso-countries)	105x faster
Currency Symbol	0.002 ms	0.18 ms	90x faster
Multi-Entity Search	1.85 ms	45.0 ms (Custom Regex)	24x faster
Phone Validation	0.012 ms	3.50 ms (libphonenumber-js)	290x faster
Cloudflare Worker Cold Start	< 1 ms	~45 ms (Heavy JSON imports)	45x faster

---

📜 License

MIT License © WorldKit