tele_number_utils 1.0.0

package/README.md

@@ -0,0 +1,196 @@
+# 📞 Phone Utils
+
+A lightweight and fully TypeScript-ready utility library for **phone number parsing, formatting, and country detection**.
+Handles tricky scenarios like **shared country codes** (e.g., +1, +44, +7) and **dependencies** (UK Crown dependencies, US territories, Canadian area codes).
+
+---
+
+## Features
+
+- Parse phone numbers into **country, calling code, national number, and formatted string**.
+- Detect countries with **shared dialing codes**:
+  - +1 → US, Canada, Puerto Rico, Caribbean nations
+  - +44 → UK, Isle of Man, Jersey, Guernsey
+  - +7 → Russia, Kazakhstan
+  - +672 → Australian territories
+
+- Format phone numbers **dynamically** with custom group sizes and separators:
+  - Separators: space (` `), dash (`-`), slash (`/`), parentheses (`()`)
+
+- Fully **TypeScript-ready** with types and interfaces
+- Minimal **dependency-free** footprint
+
+---
+
+## Installation
+
+```bash
+npm install tele_number_utils
+# or
+yarn add tele_number_utils
+```
+
+---
+
+## Usage
+
+### Parsing Phone Numbers
+
+```ts
+import { parsePhoneNumber } from "tele_number_utils";
+
+const parsed = parsePhoneNumber("+14165551234");
+console.log(parsed);
+/*
+{
+  country: "CA",
+  callingCode: "1",
+  nationalNumber: "4165551234",
+  formatted: "+1 4165551234"
+}
+*/
+```
+
+### Detecting Country from Number
+
+```ts
+import { getCountry } from "tele_number_utils";
+
+console.log(getCountry("+12015551234")); // US
+console.log(getCountry("+14165551234")); // Canada
+console.log(getCountry("+17875551234")); // Puerto Rico
+console.log(getCountry("+442071234567")); // United Kingdom
+console.log(getCountry("+441632960123")); // Isle of Man
+console.log(getCountry("+79161234567")); // Russia
+console.log(getCountry("+76171234567")); // Kazakhstan
+
+interface Country {
+  name: string;
+  dialingCode: string;
+  flagUrl: string;
+  alphaTwoCode: string;
+}
+```
+
+### Formatting Numbers
+
+```ts
+import { formatter } from "tele_number_utils";
+
+// Default grouping [3,3,4]
+console.log(formatter("1234567890")); // "123 456 7890"
+
+// Custom grouping with dash separator
+console.log(formatter("123456789012345", [4, 4, 4, 4], "-")); // "1234-5678-9012-345"
+
+// Parentheses style
+console.log(formatter("1234567890", [3, 3, 4], "()")); // "(123) 456 7890"
+
+// Short numbers <= 6 digits remain unchanged
+console.log(formatter("12345")); // "12345"
+```
+
+---
+
+## Live Console Demo
+
+```ts
+import { getCountry } from "tele_number_utils";
+
+const testNumbers = [
+  "+12015551234", // US
+  "+14165551234", // Canada
+  "+17875551234", // Puerto Rico
+  "+442071234567", // UK main
+  "+441632960123", // Isle of Man
+  "+441534123456", // Jersey
+  "+441481987654", // Guernsey
+  "+79161234567", // Russia
+  "+76171234567", // Kazakhstan
+  "+67212345678", // Australian territory
+  "+919876543210", // India
+  "+4915123456789", // Germany
+  "4915123456789", // Missing +
+  "+999123456789", // Unknown
+];
+
+console.log("===== Phone Number Country Detection =====");
+for (const number of testNumbers) {
+  const country = getCountry(number);
+  console.log(`${number} =>`, country);
+}
+```
+
+**Sample Output:**
+
+```
++12015551234 => United States
++14165551234 => Canada
++17875551234 => Puerto Rico
++442071234567 => United Kingdom
++441632960123 => Isle of Man
++441534123456 => Jersey
++441481987654 => Guernsey
++79161234567 => Russia
++76171234567 => Kazakhstan
++67212345678 => Australia
++919876543210 => India
++4915123456789 => Germany
+4915123456789 => Invalid Phone number
++999123456789 => Country not found
+```
+
+---
+
+## API
+
+### `parsePhoneNumber(phone: string): ParsedPhoneNumber`
+
+Parses a phone number string into:
+
+```ts
+interface ParsedPhoneNumber {
+  country?: string; // ISO Alpha-2 country code
+  callingCode?: string; // Dialing code
+  nationalNumber?: string;
+  formatted?: string; // Formatted string
+}
+```
+
+---
+
+### `getCountry(number: string): Country | string`
+
+Returns country information for a given number:
+
+```ts
+interface Country {
+  name: string;
+  dialingCode: string;
+  flagUrl: string;
+  alphaTwoCode: string;
+}
+```
+
+Returns "Invalid Phone number" or "Country not found" for invalid/unknown numbers.
+
+---
+
+### `formatter(value: string, groupSizes?: number[], separator?: " " | "-" | "/" | "()"): string`
+
+Formats digits into **custom groups**.
+
+- `groupSizes` – array of numbers specifying group lengths, default `[3,3,4]`
+- `separator` – separator between groups, default `" "`
+
+---
+
+## Contributing
+
+Feel free to open an issue or PR to improve country detection, formatting options, or add more NANPA countries.
+
+---
+
+## License
+
+MIT

package/dist/country/country.d.ts

@@ -0,0 +1,7 @@
+export declare const country_list: {
+    name: string;
+    dialingCode: string;
+    flagUrl: string;
+    alphaTwoCode: string;
+}[];
+//# sourceMappingURL=country.d.ts.map

package/dist/country/country.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"country.d.ts","sourceRoot":"","sources":["../../src/country/country.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,YAAY;;;;;GA69CxB,CAAC"}