Skip to content
This repository was archived by the owner on Nov 22, 2025. It is now read-only.
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
107 commits
Select commit Hold shift + click to select a range
e4bdc58
chore: update release
meabed Feb 12, 2025
88bba6c
chore: update pkgs
meabed Feb 12, 2025
e36881c
chore: update pkgs
meabed Feb 12, 2025
7b75c89
chore(deps): update dependency @types/node to v22.13.2 (#269)
renovate[bot] Feb 13, 2025
954e6ea
chore(deps): update dependency prettier to v3.5.1 (#270)
renovate[bot] Feb 13, 2025
bd7d6be
chore(deps): update dependency @types/node to v22.13.4 (#271)
renovate[bot] Feb 14, 2025
898bc91
chore(deps): update dependency rollup to v4.34.7 (#272)
renovate[bot] Feb 14, 2025
5100296
Merge branch 'master' of github.com:devmehq/libphonenumber-js into de…
meabed Feb 16, 2025
e805284
chore: update pkgs
meabed Feb 16, 2025
d03cc92
fix(deps): update dependency libphonenumber-js to v1.11.20 (#277)
renovate[bot] Feb 16, 2025
6cb8777
chore(deps): update dependency rollup to v4.34.8 (#278)
renovate[bot] Feb 17, 2025
12de6ce
fix(deps): update dependency bson to v6.10.3 (#279)
renovate[bot] Feb 20, 2025
0ccb2ec
chore(deps): update dependency @types/node to v22.13.5 (#280)
renovate[bot] Feb 22, 2025
cda3849
chore(deps): update dependency prettier to v3.5.2 (#281)
renovate[bot] Feb 22, 2025
ac54a66
chore(deps): update dependency ts-jest to v29.2.6 (#282)
renovate[bot] Feb 23, 2025
bbb1497
fix(deps): update dependency libphonenumber-js to v1.12.4 (#283)
renovate[bot] Feb 27, 2025
f331871
chore(deps): update all non-major dependencies (#284)
renovate[bot] Mar 1, 2025
8c00da9
chore(deps): update all non-major dependencies (#285)
renovate[bot] Mar 1, 2025
84d8bac
chore(deps): update dependency prettier to v3.5.3 (#286)
renovate[bot] Mar 3, 2025
4d5871d
chore(deps): update dependency @types/node to v22.13.9 (#287)
renovate[bot] Mar 4, 2025
4869182
fix(deps): update dependency libphonenumber-js to v1.12.5 (#288)
renovate[bot] Mar 5, 2025
3e86ea0
chore(deps): update all non-major dependencies (#289)
renovate[bot] Mar 8, 2025
b172d23
chore(deps): update dependency shelljs to ^0.9.0 (#290)
renovate[bot] Mar 9, 2025
66b1da4
fix(deps): update dependency libphonenumber-js to v1.12.6 (#291)
renovate[bot] Mar 13, 2025
0270e75
chore(deps): update dependency shelljs to v0.9.2 (#292)
renovate[bot] Mar 17, 2025
ea395ab
chore(deps): update dependency rollup to v4.36.0 (#293)
renovate[bot] Mar 17, 2025
f3cc83e
chore: update packages
meabed Mar 19, 2025
628e834
chore(deps): update dependency @types/node to v22.13.11 (#294)
renovate[bot] Mar 21, 2025
ce59737
chore(deps): update dependency rollup to v4.37.0 (#295)
renovate[bot] Mar 23, 2025
8000879
chore(deps): update all non-major dependencies (#296)
renovate[bot] Mar 24, 2025
41dda6d
chore(deps): update dependency @types/node to v22.13.14 (#297)
renovate[bot] Mar 27, 2025
98b14ba
chore(deps): update dependency rollup to v4.38.0 (#298)
renovate[bot] Mar 29, 2025
2c5c8a3
chore(deps): update dependency ts-jest to v29.3.1 (#299)
renovate[bot] Apr 1, 2025
7e1ad96
chore(deps): update all non-major dependencies (#300)
renovate[bot] Apr 2, 2025
6d733e7
chore(deps): update dependency @types/node to v22.14.0 (#301)
renovate[bot] Apr 3, 2025
f9506df
chore(deps): update dependency typescript to v5.8.3 (#302)
renovate[bot] Apr 5, 2025
8b25364
chore(deps): update dependency @types/node to v22.14.1 (#303)
renovate[bot] Apr 12, 2025
6c6e917
chore(deps): update dependency rollup to v4.40.0 (#304)
renovate[bot] Apr 12, 2025
d4170a8
chore(deps): update dependency ts-jest to v29.3.2 (#305)
renovate[bot] Apr 13, 2025
c51a990
fix(deps): update dependency libphonenumber-js to v1.12.7 (#306)
renovate[bot] Apr 17, 2025
096bebd
chore(deps): update dependency @release-it/conventional-changelog to …
renovate[bot] Apr 18, 2025
79a70b3
chore(deps): update dependency @types/node to v22.15.0 (#310)
renovate[bot] Apr 25, 2025
6988304
chore(deps): update dependency @types/node to v22.15.2 (#311)
renovate[bot] Apr 25, 2025
e8820ea
chore(deps): update all non-major dependencies (#312)
renovate[bot] Apr 28, 2025
03ccd85
chore(deps): update dependency @types/node to v22.15.9 (#313)
renovate[bot] May 6, 2025
4b6310f
chore(deps): update all non-major dependencies (#314)
renovate[bot] May 6, 2025
652094d
chore(deps): update dependency @types/node to v22.15.14 (#315)
renovate[bot] May 7, 2025
52a5a2a
fix(deps): update all non-major dependencies (#316)
renovate[bot] May 7, 2025
600b7c1
chore(deps): update dependency @types/node to v22.15.16 (#317)
renovate[bot] May 8, 2025
4aed437
chore(deps): update all non-major dependencies (#318)
renovate[bot] May 9, 2025
fe60c68
chore(deps): update dependency shelljs to ^0.10.0 (#319)
renovate[bot] May 10, 2025
7d055a2
chore(deps): update dependency release-it to v19 (#309)
renovate[bot] May 10, 2025
f88f120
chore(deps): update dependency @types/node to v22.15.18 (#320)
renovate[bot] May 14, 2025
680bad2
chore(deps): update dependency ts-jest to v29.3.3 (#321)
renovate[bot] May 14, 2025
4c6f7de
chore(deps): update dependency ts-jest to v29.3.4 (#322)
renovate[bot] May 16, 2025
3a43d0a
chore(deps): update dependency rollup to v4.41.0 (#323)
renovate[bot] May 18, 2025
5b41116
chore(deps): update dependency @types/node to v22.15.19 (#324)
renovate[bot] May 19, 2025
45e76a8
chore(deps): update dependency @types/node to v22.15.21 (#325)
renovate[bot] May 21, 2025
4520bcc
chore(deps): update dependency rollup to v4.41.1 (#326)
renovate[bot] May 24, 2025
3542d68
chore(deps): update dependency @types/node to v22.15.22 (#327)
renovate[bot] May 27, 2025
aa1d120
chore(deps): update dependency @types/node to v22.15.23 (#328)
renovate[bot] May 28, 2025
0a60886
chore(deps): update dependency @types/node to v22.15.24 (#329)
renovate[bot] May 29, 2025
0542616
chore(deps): update dependency @types/node to v22.15.26 (#330)
renovate[bot] May 30, 2025
d84e29d
chore(deps): update all non-major dependencies (#331)
renovate[bot] May 30, 2025
3ea7389
chore(deps): update dependency @types/node to v22.15.29 (#332)
renovate[bot] May 31, 2025
24b13aa
fix(deps): update dependency bson to v6.10.4 (#333)
renovate[bot] Jun 3, 2025
8485027
fix(deps): update dependency libphonenumber-js to v1.12.9 (#334)
renovate[bot] Jun 5, 2025
875f5de
chore(deps): update all non-major dependencies (#335)
renovate[bot] Jun 7, 2025
8a1b4e2
chore(deps): update dependency @types/node to v22.15.31 (#336)
renovate[bot] Jun 10, 2025
2f6c867
chore(deps): update dependency rollup to v4.43.0 (#338)
renovate[bot] Jun 11, 2025
c4e4694
chore(deps): update dependency ts-jest to v29.4.0 (#339)
renovate[bot] Jun 12, 2025
05a1fdc
chore(deps): update dependency @types/node to v22.15.32 (#340)
renovate[bot] Jun 16, 2025
b5b47d9
chore(deps): update dependency rollup to v4.44.0 (#341)
renovate[bot] Jun 19, 2025
ed79a13
chore(deps): update dependency prettier to v3.6.0 (#342)
renovate[bot] Jun 23, 2025
4473325
chore(deps): update dependency @types/node to v22.15.33 (#343)
renovate[bot] Jun 24, 2025
37870b3
chore(deps): update dependency prettier to v3.6.1 (#344)
renovate[bot] Jun 25, 2025
ea3cfda
chore(deps): update dependency rollup to v4.44.1 (#345)
renovate[bot] Jun 26, 2025
67b189a
chore(deps): update dependency prettier to v3.6.2 (#346)
renovate[bot] Jun 27, 2025
fd8346f
chore(deps): update dependency @types/node to v22.15.34 (#347)
renovate[bot] Jun 28, 2025
92799d1
chore(deps): update all non-major dependencies (#348)
renovate[bot] Jul 2, 2025
0b40f51
chore(deps): update jest monorepo to v30 (#337)
renovate[bot] Jul 2, 2025
fdd321f
chore(deps): update dependency jest to v30.0.4 (#349)
renovate[bot] Jul 3, 2025
05ea7d6
chore(deps): update dependency rollup to v4.44.2 (#350)
renovate[bot] Jul 4, 2025
8167d3e
chore(deps): update dependency @types/node to v22.16.2 (#351)
renovate[bot] Jul 9, 2025
dfb701e
chore(deps): update dependency @types/node to v22.16.3 (#352)
renovate[bot] Jul 10, 2025
7b35821
chore(deps): update dependency rollup to v4.45.0 (#353)
renovate[bot] Jul 12, 2025
f5fdaac
fix(deps): update dependency libphonenumber-js to v1.12.10 (#354)
renovate[bot] Jul 14, 2025
bc7bd33
chore(deps): update all non-major dependencies (#355)
renovate[bot] Jul 15, 2025
1dcc779
chore(deps): update dependency release-it to v19.0.4 (#356)
renovate[bot] Jul 17, 2025
4bbc574
chore(deps): update dependency @types/node to v22.16.5 (#357)
renovate[bot] Jul 19, 2025
c327999
chore(deps): update dependency jest to v30.0.5 (#358)
renovate[bot] Jul 22, 2025
cb4fdef
chore(deps): update dependency rollup to v4.45.3 (#359)
renovate[bot] Jul 26, 2025
cf940b7
chore(deps): update dependency rollup to v4.46.0 (#360)
renovate[bot] Jul 27, 2025
ed997b4
chore(deps): update dependency rollup to v4.46.1 (#361)
renovate[bot] Jul 28, 2025
a2e64e7
chore(deps): update all non-major dependencies (#362)
renovate[bot] Jul 30, 2025
53318cc
chore(deps): update dependency typescript to v5.9.2 (#363)
renovate[bot] Aug 1, 2025
43ae1af
chore(deps): update dependency ts-jest to v29.4.1 (#364)
renovate[bot] Aug 3, 2025
86a8c4b
chore(deps): update dependency @types/node to v22.17.1 (#365)
renovate[bot] Aug 8, 2025
9a1eb2e
chore(deps): update actions/checkout action to v5 (#366)
renovate[bot] Aug 11, 2025
99d18f2
fix(deps): update dependency libphonenumber-js to v1.12.11 (#367)
renovate[bot] Aug 13, 2025
bf753b8
fix(deps): update dependency libphonenumber-js to v1.12.12 (#368)
renovate[bot] Aug 14, 2025
55cc0e1
chore(deps): update dependency @types/node to v22.17.2 (#369)
renovate[bot] Aug 15, 2025
3232334
chore(deps): update dependency rollup to v4.46.3 (#370)
renovate[bot] Aug 18, 2025
df2513b
feat: Implement comprehensive improvements to phone-number-validator-js
meabed Aug 19, 2025
27988e0
Release 1.4.0-develop.0
Aug 19, 2025
d350af3
docs: Add comprehensive documentation for new features
meabed Aug 19, 2025
1baa0bf
chore: update
meabed Aug 19, 2025
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 5 additions & 2 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@ on:
push:
paths:
- 'src/**'
- '__tests__/**'
- 'package.json'
- 'yarn.lock'
- 'release.config.js'
Expand Down Expand Up @@ -36,10 +37,9 @@ jobs:
steps:
- run: echo "🎉 The job was automatically triggered by a ${{ github.event_name }} event."

- uses: actions/checkout@v4
- uses: actions/checkout@v5
with:
fetch-depth: 30
persist-credentials: false

- uses: FranzDiebold/github-env-vars-action@v2

Expand All @@ -59,4 +59,7 @@ jobs:
- name: Release
if: github.ref == 'refs/heads/develop'
run: |
git config --global user.email "support@dev.me"
git config --global user.name "Dev.me Team"
npm set //registry.npmjs.org/:_authToken $NPM_TOKEN
node release.mjs
6 changes: 4 additions & 2 deletions .github/workflows/release.yml
Original file line number Diff line number Diff line change
Expand Up @@ -30,10 +30,9 @@ jobs:
steps:
- run: echo "🎉 The job was automatically triggered by a ${{ github.event_name }} event."

- uses: actions/checkout@v4
- uses: actions/checkout@v5
with:
fetch-depth: 30
persist-credentials: false

- uses: FranzDiebold/github-env-vars-action@v2

Expand All @@ -52,4 +51,7 @@ jobs:

- name: Release
run: |
git config --global user.email "support@dev.me"
git config --global user.name "Dev.me Team"
npm set //registry.npmjs.org/:_authToken $NPM_TOKEN
node release.mjs
303 changes: 303 additions & 0 deletions API.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,303 @@
# API Documentation

## Table of Contents
- [Core Functions](#core-functions)
- [geocoder](#geocoder)
- [carrier](#carrier)
- [timezones](#timezones)
- [Cache Management](#cache-management)
- [clearCache](#clearcache)
- [getCacheSize](#getcachesize)
- [setCacheSize](#setcachesize)
- [Type Definitions](#type-definitions)
- [Locales](#locales)

## Core Functions

### geocoder

Provides geographical information related to a phone number.

```typescript
geocoder(
phonenumber: PhoneNumber | undefined,
locale?: GeocoderLocale
): string | null
```

#### Parameters
- `phonenumber` - A parsed phone number object from `libphonenumber-js`
- `locale` - Optional locale for localized location names (default: `'en'`)

#### Returns
- Location name as string if found
- `null` if no location data available or invalid input

#### Example
```javascript
import { geocoder, parsePhoneNumberFromString } from '@devmehq/phone-number-validator-js'

const phoneNumber = parsePhoneNumberFromString('+41431234567')
const locationEN = geocoder(phoneNumber) // "Zurich"
const locationDE = geocoder(phoneNumber, 'de') // "Zürich"
```

---

### carrier

Maps a phone number to its original carrier.

**Note:** This method returns the original carrier assigned to the number range, not the current carrier if the number has been ported.

```typescript
carrier(
phonenumber: PhoneNumber | undefined,
locale?: CarrierLocale
): string | null
```

#### Parameters
- `phonenumber` - A parsed phone number object from `libphonenumber-js`
- `locale` - Optional locale for localized carrier names (default: `'en'`)

#### Returns
- Carrier name as string if found
- `null` if no carrier data available (e.g., landline numbers) or invalid input

#### Example
```javascript
import { carrier, parsePhoneNumberFromString } from '@devmehq/phone-number-validator-js'

const phoneNumber = parsePhoneNumberFromString('+8619912345678')
const carrierEN = carrier(phoneNumber) // "China Telecom"
const carrierZH = carrier(phoneNumber, 'zh') // "中国电信"
```

---

### timezones

Provides all timezones associated with a phone number.

```typescript
timezones(
phonenumber: PhoneNumber | undefined
): string[] | null
```

#### Parameters
- `phonenumber` - A parsed phone number object from `libphonenumber-js`

#### Returns
- Array of timezone identifiers (e.g., `['America/New_York']`)
- `null` if no timezone data available or invalid input

#### Example
```javascript
import { timezones, parsePhoneNumberFromString } from '@devmehq/phone-number-validator-js'

const phoneNumber = parsePhoneNumberFromString('+12124567890')
const tzs = timezones(phoneNumber) // ['America/New_York']
```

## Cache Management

The library uses an LRU (Least Recently Used) cache to optimize performance. The cache automatically evicts the least recently used entries when it reaches its size limit.

### clearCache

Clears all cached data. Useful for memory management in long-running processes.

```typescript
clearCache(): void
```

#### Example
```javascript
import { clearCache } from '@devmehq/phone-number-validator-js'

// Clear all cached data
clearCache()
```

---

### getCacheSize

Returns the current number of items in the cache.

```typescript
getCacheSize(): number
```

#### Returns
- Number of cached entries

#### Example
```javascript
import { getCacheSize } from '@devmehq/phone-number-validator-js'

const size = getCacheSize()
console.log(`Current cache size: ${size}`)
```

---

### setCacheSize

Sets the maximum cache size. When the cache reaches this limit, the least recently used entries are evicted.

```typescript
setCacheSize(size: number): void
```

#### Parameters
- `size` - Maximum number of entries to cache

#### Example
```javascript
import { setCacheSize } from '@devmehq/phone-number-validator-js'

// Limit cache to 50 entries
setCacheSize(50)

// Increase cache for better performance (uses more memory)
setCacheSize(200)

// Reduce cache for lower memory usage
setCacheSize(10)
```

## Type Definitions

### PhoneNumber

The `PhoneNumber` type is exported from `libphonenumber-js`. It represents a parsed phone number with various properties:

```typescript
interface PhoneNumber {
country?: string
countryCallingCode: string
nationalNumber: string
number: string
// ... other properties
}
```

### GeocoderLocale

Supported locales for geocoding:

```typescript
type GeocoderLocale = 'ar' | 'be' | 'bg' | 'bs' | 'de' | 'el' | 'en' |
'es' | 'fa' | 'fi' | 'fr' | 'hr' | 'hu' | 'hy' | 'id' | 'it' | 'iw' |
'ja' | 'ko' | 'nl' | 'pl' | 'pt' | 'ro' | 'ru' | 'sq' | 'sr' | 'sv' |
'th' | 'tr' | 'uk' | 'vi' | 'zh' | 'zh_Hant'
```

### CarrierLocale

Supported locales for carrier information:

```typescript
type CarrierLocale = 'ar' | 'be' | 'en' | 'fa' | 'ko' | 'ru' | 'uk' |
'zh' | 'zh_Hant'
```

## Locales

### Locale Fallback

When a requested locale is not available for a specific phone number, the library automatically falls back to English (`'en'`).

### Available Locales by Region

#### Geocoding Locales
- **Arabic** (`ar`): Middle East regions
- **Chinese Simplified** (`zh`): Mainland China
- **Chinese Traditional** (`zh_Hant`): Hong Kong, Taiwan
- **English** (`en`): Default, worldwide coverage
- **German** (`de`): Germany, Austria, Switzerland
- **Spanish** (`es`): Spain, Latin America
- **French** (`fr`): France, French-speaking regions
- And many more...

#### Carrier Locales
- **Arabic** (`ar`): Middle East carriers
- **Chinese** (`zh`): Chinese carriers
- **English** (`en`): Default, worldwide carriers
- **Korean** (`ko`): Korean carriers
- **Russian** (`ru`): Russian carriers

## Performance Considerations

### Caching Strategy

The library uses [tiny-lru](https://www.npmjs.com/package/tiny-lru) for optimal performance:

1. **First Lookup**: Loads data from disk (slower, ~10-50ms)
2. **Subsequent Lookups**: Retrieves from cache (<1ms)
3. **Cache Eviction**: Automatic LRU eviction when limit reached

### Memory Management

For long-running applications:

```javascript
import { setCacheSize, clearCache, getCacheSize } from '@devmehq/phone-number-validator-js'

// Option 1: Limit cache size
setCacheSize(50) // Balance between performance and memory

// Option 2: Periodic cache clearing
setInterval(() => {
if (getCacheSize() > 80) {
clearCache()
}
}, 3600000) // Check every hour

// Option 3: Dynamic adjustment based on memory
const checkMemory = () => {
const usage = process.memoryUsage()
if (usage.heapUsed > 100 * 1024 * 1024) { // 100MB
setCacheSize(10) // Reduce cache
} else {
setCacheSize(100) // Normal cache
}
}
```

## Error Handling

All functions handle invalid inputs gracefully:

```javascript
import { geocoder, carrier, timezones } from '@devmehq/phone-number-validator-js'

// All return null for invalid inputs
geocoder(undefined) // null
geocoder(null) // null
carrier(undefined) // null
timezones(undefined) // null

// Invalid phone numbers
const invalid = parsePhoneNumberFromString('invalid')
geocoder(invalid) // null
```

## Development vs Production

In development mode (`NODE_ENV !== 'production'`), the library logs errors to help with debugging:

```bash
# Development mode - shows error logs
yarn test

# Production mode - suppresses error logs
NODE_ENV=production yarn test
```

## Thread Safety

The library is thread-safe for read operations. However, cache management operations (`setCacheSize`, `clearCache`) should be synchronized in multi-threaded environments.
19 changes: 19 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,24 @@
# Changelog

## v1.4.0 (Unreleased)
### Features
- Add high-performance LRU caching using tiny-lru library
- Add cache management API: `clearCache()`, `getCacheSize()`, `setCacheSize()`
- Add comprehensive input validation and error handling
- Improve TypeScript type safety with explicit return types

### Improvements
- Refactor code to eliminate duplication between geocoder and carrier functions
- Optimize memory usage with configurable cache limits
- Add 27 new comprehensive test cases
- Enhance error logging in development mode
- Performance improvements: <1ms lookups after initial cache

### Documentation
- Add comprehensive API documentation
- Add performance and memory management guides
- Update README with cache management examples

## v1.3.0
- Update dependencies

Expand Down
Loading