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.

🎯 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

Key Features

✨ 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

Global Installation (Recommended)

npm install -g npm-gitnamecheck

Local Installation

npm install npm-gitnamecheck

---

🚀 Quick Start

1. Create a wordlist file

Create wordlist.txt with names to check (one per line):

myawesomeapp
cooltoolkit
devutils
brandname

2. Run the checker

npx npm-gitnamecheck wordlist.txt

3. View results

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

Basic Usage

npm-gitnamecheck wordlist.txt

Advanced Options

npm-gitnamecheck wordlist.txt \
  --concurrency 20 \
  --retries 5 \
  --github-token ghp_yourtoken \
  --out ./results

Command Line Options

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:

1. Generate Token

Visit GitHub Settings → Developer Settings → Personal Access Tokens

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

2. Use Token

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

Environment Variable (Alternative):

export GITHUB_TOKEN=ghp_yourtoken
npm-gitnamecheck wordlist.txt

---

📊 Output Formats

1. free-names.txt

Plain text list of fully available names:

myawesomeapp
devutils

2. free-names.json

Structured data with metadata:

[
  {
    "name": "myawesomeapp",
    "when": "2025-11-08T12:34:56.789Z"
  }
]

3. names-report.csv

Comprehensive report with all checks:

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

Validation Process

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

Loading

Retry Logic

• 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

Rate Limiting Protection

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

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

1. Brand Name Validation

# Check if your brand name is available
echo "mybrand" > brand.txt
npm-gitnamecheck brand.txt

2. Bulk Package Audit

# Audit 1000 potential names with high concurrency
npm-gitnamecheck candidates.txt --concurrency 30 --retries 5

3. CI/CD Integration

# Validate names before release
npm-gitnamecheck names.txt --out ./build/reports

4. Namespace Squatting Detection

# Check variations of your brand
npm-gitnamecheck variations.txt --github-token $GITHUB_TOKEN

---

⚙️ Configuration Examples

High-Speed Checking (Aggressive)

npm-gitnamecheck wordlist.txt \
  --concurrency 50 \
  --retries 2 \
  --github-token $GITHUB_TOKEN

Conservative (Network-Friendly)

npm-gitnamecheck wordlist.txt \
  --concurrency 5 \
  --retries 10

Behind Corporate Proxy

npm-gitnamecheck wordlist.txt \
  --proxy http://proxy.company.com:8080 \
  --github-token $GITHUB_TOKEN

---

🛠️ Troubleshooting

Rate Limiting Issues

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

Network Timeouts

Symptom: error: AbortError or timeout messages

Solutions:

1. Check network connectivity
2. Increase timeout in code (modify fetchWithTimeout)
3. Use --proxy if behind firewall

Invalid Name Errors

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