NPM-GitNameCheck 🔍

A professional name availability checker that validates package/username availability across NPM and GitHub ecosystems with advanced rate limiting, retry logic, and comprehensive reporting.

![npm version](https://www.npmjs.com/package/npm-gitnamecheck)
![License: MIT](https://opensource.org/licenses/MIT)

🎯 Overview

NPM-GitNameCheck is a sophisticated CLI tool designed for developers, brand managers, and organizations who need to:
- Find available names across multiple platforms simultaneously
- Validate brand consistency before launching new projects
- Audit namespace availability for package ecosystems
- Generate comprehensive reports for decision-making

$3

✨ Multi-Platform Checking
- NPM package registry
- GitHub username/organization
- GitHub repository availability
- Direct GitHub URL validation

🚀 Enterprise-Grade Performance
- Configurable concurrency (default: 10 parallel checks)
- Intelligent retry mechanism with exponential backoff
- Jittered delays to prevent rate limiting
- Timeout protection for network calls

📊 Professional Reporting
- JSON output for programmatic processing
- Plain text for quick reference
- CSV with detailed status per service
- Timestamped results with error tracking

🔒 Production Ready
- DNS-safe name validation
- GitHub token support for higher rate limits
- Proxy support for restricted environments
- Graceful error handling

---

📦 Installation

$3

bash

npm install -g npm-gitnamecheck

$3

bash

npm install npm-gitnamecheck





---



🚀 Quick Start



$3



Create

wordlist.txt

 with names to check (one per line):

text

myawesomeapp

cooltoolkit

devutils

brandname

$3

bash

npx npm-gitnamecheck wordlist.txt





$3



The tool generates three files in your current directory:

-

free-names.txt

 - Simple list of fully available names

-

free-names.json

 - Structured data with timestamps

-

names-report.csv

 - Detailed report with per-service status



---



📖 Usage



$3

bash

npm-gitnamecheck wordlist.txt

$3

bash

npm-gitnamecheck wordlist.txt \

  --concurrency 20 \

  --retries 5 \

  --github-token ghp_yourtoken \

  --out ./results





$3



| Option | Description | Default |

|--------|-------------|---------|

|

--concurrency N | Number of parallel checks | 10

 |

|

--retries N | Retry attempts for failed requests | 3

 |

|

--github-token TOKEN | GitHub personal access token | null

 |

|

--proxy PROXY | HTTP(S) proxy URL | null

 |

|

--out DIR

 | Output directory for results | Current directory |



---



🔐 GitHub Token Setup



For higher rate limits (5,000 req/hour vs 60 req/hour), use a GitHub token:



$3



Visit GitHub Settings → Developer Settings → Personal Access Tokens



Required permissions: No special scopes needed (public access only)



$3

bash

npm-gitnamecheck wordlist.txt --github-token ghp_yourtoken





Environment Variable (Alternative):

bash

export GITHUB_TOKEN=ghp_yourtoken

npm-gitnamecheck wordlist.txt





---



📊 Output Formats



$3

Plain text list of fully available names:

text

myawesomeapp

devutils





$3

Structured data with metadata:

json

[

  {

    "name": "myawesomeapp",

    "when": "2025-11-08T12:34:56.789Z"

  }

]





$3

Comprehensive report with all checks:

csv

name,ok,start,end,services,raw_results

myawesomeapp,true,2025-11-08T12:34:56Z,2025-11-08T12:34:58Z,"npm:free|github:user:free|github:repo:free|github:web:free","[...]"

brandname,false,2025-11-08T12:34:56Z,2025-11-08T12:34:59Z,"npm:taken|github:user:free|github:repo:free|github:web:free","[...]"





---



🏗️ How It Works



$3

mermaid

graph TD

    A[Read Wordlist] --> B[Normalize Names]

    B --> C{DNS-Safe?}

    C -->|No| D[Mark Invalid]

    C -->|Yes| E[Parallel Checks]

    E --> F[NPM Registry]

    E --> G[GitHub User API]

    E --> H[GitHub Repo API]

    E --> I[GitHub Web Check]

    F --> J[Aggregate Results]

    G --> J

    H --> J

    I --> J

    J --> K{All Free?}

    K -->|Yes| L[Add to Free List]

    K -->|No| M[Mark as Taken]

    L --> N[Generate Reports]

    M --> N





$3



- Exponential backoff:

200ms × 2^attempt for NPM, 300ms × 2^attempt

 for GitHub

- Jitter: Random variance to prevent thundering herd

- Configurable: Adjust retry count based on network conditions



$3



1. Concurrency control: Limits parallel requests

2. Jittered delays: 100-600ms between batches

3. Request spacing: 150-350ms between individual checks

4. Timeout protection: 8-9 second timeouts per request



---



🔧 Programmatic Usage

javascript

import { checkName, checkNpm, checkGitHubUser } from 'npm-gitnamecheck';



// Check single name across all services

const result = await checkName('mypackage');

console.log(result);

// {

//   name: 'mypackage',

//   ok: true,

//   results: [

//     { service: 'npm', status: 'free', code: 404 },

//     { service: 'github:user', status: 'free', code: 404 },

//     ...

//   ]

// }



// Check specific service

const npmStatus = await checkNpm('mypackage');

console.log(npmStatus); // { service: 'npm', status: 'free', code: 404 }





---



🎯 Use Cases



$3

bash

Check if your brand name is available

echo "mybrand" > brand.txt

npm-gitnamecheck brand.txt

$3

bash

Audit 1000 potential names with high concurrency

npm-gitnamecheck candidates.txt --concurrency 30 --retries 5

$3

bash

Validate names before release

npm-gitnamecheck names.txt --out ./build/reports

$3

bash

Check variations of your brand

npm-gitnamecheck variations.txt --github-token $GITHUB_TOKEN





---



⚙️ Configuration Examples



$3

bash

npm-gitnamecheck wordlist.txt \

  --concurrency 50 \

  --retries 2 \

  --github-token $GITHUB_TOKEN

$3

bash

npm-gitnamecheck wordlist.txt \

  --concurrency 5 \

  --retries 10

$3

bash

npm-gitnamecheck wordlist.txt \

  --proxy http://proxy.company.com:8080 \

  --github-token $GITHUB_TOKEN





---



🛠️ Troubleshooting



$3



Symptom: Many

status: 'error'

 results



Solutions:

1. Reduce

--concurrency (try 5

)

2. Add GitHub token with

--github-token



3. Increase

--retries to 5 or 10





$3



Symptom:

error: AbortError

 or timeout messages



Solutions:

1. Check network connectivity

2. Increase timeout in code (modify

fetchWithTimeout

)

3. Use

--proxy

 if behind firewall



$3



Symptom:

status: 'invalid'

 for valid-looking names



Validation rules:

- Must be lowercase

- Only

a-z, 0-9, -, _` allowed
- No spaces or special characters

---

📝 Best Practices

1. Use GitHub Token: Always use a token for serious checking
2. Start Conservative: Begin with low concurrency (10), increase if stable
3. Batch Processing: For >1000 names, split into multiple runs
4. Monitor Output: Watch console for errors during execution
5. Validate Input: Ensure wordlist has one name per line, no empty lines

---

🤝 Contributing

Contributions welcome! Areas for improvement:

- [ ] Additional services (PyPI, Docker Hub, etc.)
- [ ] Progress bar for long-running checks
- [ ] Resume functionality for interrupted runs
- [ ] Domain availability checking
- [ ] Social media handle checking

---

📄 License

MIT License - see LICENSE file for details

---

👨‍💻 Author

Farbod Akvan
Published by FireXCore

- Website: firexcore.com
- GitHub: @FireXCore

---

🙏 Acknowledgments

Built with modern Node.js APIs and designed for real-world production use. Special thanks to the open-source community for inspiration and feedback.

---

📞 Support

- Issues: GitHub Issues
- Questions: Open a discussion or contact via firexcore.com
- Security: Report vulnerabilities privately via GitHub Security Advisory

---

Made with ❤️ by FireXCore