tessl/npm-ip

IP address utilities for node.js providing IPv4/IPv6 address manipulation, validation, and network operations

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Network Interface Operations

Name: tessl/npm-ip
Author: tessl

Functions for querying local network interfaces and retrieving IP addresses from the system with support for interface-specific queries and address family filtering.

Capabilities

Network Interface Queries

address

Retrieves IP addresses from local network interfaces with flexible filtering options for interface names and address families.

/**
 * Gets IP address from network interface
 * @param {string} [name] - Interface name, 'public', 'private', or undefined
 * @param {string|number} [family] - 'ipv4', 'ipv6', 4, 6, or undefined (defaults to 'ipv4')
 * @returns {string|undefined} IP address string or undefined if not found
 */
function address(name, family);

Parameter Behavior:

name:
- undefined: Returns first IPv4 address or loopback if none found
- 'public': Returns first public (non-private) IP address
- 'private': Returns first private IP address
- Interface name (e.g., 'eth0', 'wlan0'): Returns first address from specified interface
family: Address family filter ('ipv4', 'ipv6', 4, 6, or undefined for IPv4)

Usage Examples:

const ip = require('ip');

// Get default IP address (first IPv4 or loopback)
console.log(ip.address()); // e.g., '192.168.1.100'

// Get first public IP address
console.log(ip.address('public')); // e.g., '203.0.113.10'
console.log(ip.address('public', 'ipv4')); // e.g., '203.0.113.10'
console.log(ip.address('public', 'ipv6')); // e.g., '2001:db8::1'

// Get first private IP address
console.log(ip.address('private')); // e.g., '192.168.1.100'
console.log(ip.address('private', 'ipv6')); // e.g., 'fe80::1'

// Get address from specific interface
console.log(ip.address('eth0')); // e.g., '192.168.1.100'
console.log(ip.address('eth0', 'ipv6')); // e.g., 'fe80::a1b2:c3d4:e5f6'
console.log(ip.address('wlan0', 'ipv4')); // e.g., '192.168.0.50'

// Using numeric family identifiers
console.log(ip.address('public', 4)); // IPv4 public address
console.log(ip.address('private', 6)); // IPv6 private address

// Returns undefined if no matching address found
console.log(ip.address('nonexistent-interface')); // undefined
console.log(ip.address('public', 'ipv6')); // undefined (if no public IPv6)

Loopback Address Generation

loopback

Returns the standard loopback address for the specified address family.

/**
 * Returns loopback address for specified family
 * @param {string|number} [family] - 'ipv4', 'ipv6', 4, 6, or undefined (defaults to 'ipv4')
 * @returns {string} Loopback address string
 * @throws {Error} Throws error if family is not 'ipv4' or 'ipv6'
 */
function loopback(family);

Usage Examples:

const ip = require('ip');

// Default (IPv4) loopback
console.log(ip.loopback()); // '127.0.0.1'
console.log(ip.loopback('ipv4')); // '127.0.0.1'
console.log(ip.loopback(4)); // '127.0.0.1'

// IPv6 loopback
console.log(ip.loopback('ipv6')); // 'fe80::1'
console.log(ip.loopback(6)); // 'fe80::1'

// Case-insensitive family names
console.log(ip.loopback('IPV4')); // '127.0.0.1'
console.log(ip.loopback('IPv6')); // 'fe80::1'

// Error for invalid family
try {
  ip.loopback('invalid');
} catch (error) {
  console.log(error.message); // 'family must be ipv4 or ipv6'
}

Practical Usage Patterns

Server Binding and Configuration

const ip = require('ip');
const http = require('http');

// Bind server to first available private IP
const privateIp = ip.address('private');
const server = http.createServer();

if (privateIp) {
  server.listen(3000, privateIp, () => {
    console.log(`Server running on http://${privateIp}:3000`);
  });
} else {
  // Fallback to loopback
  const loopback = ip.loopback();
  server.listen(3000, loopback, () => {
    console.log(`Server running on http://${loopback}:3000`);
  });
}

Network Interface Discovery

const ip = require('ip');
const os = require('os');

function discoverNetworkInterfaces() {
  const interfaces = os.networkInterfaces();
  const results = {};
  
  for (const interfaceName of Object.keys(interfaces)) {
    results[interfaceName] = {
      ipv4: ip.address(interfaceName, 'ipv4'),
      ipv6: ip.address(interfaceName, 'ipv6')
    };
  }
  
  return results;
}

console.log(discoverNetworkInterfaces());
// {
//   eth0: { ipv4: '192.168.1.100', ipv6: 'fe80::a1b2:c3d4:e5f6' },
//   wlan0: { ipv4: '192.168.0.50', ipv6: undefined },
//   lo: { ipv4: '127.0.0.1', ipv6: '::1' }
// }

Multi-homed Host Configuration

const ip = require('ip');

function getNetworkConfiguration() {
  return {
    // Primary addresses
    primaryIPv4: ip.address(),
    primaryIPv6: ip.address(undefined, 'ipv6'),
    
    // Public addresses (for external communication)
    publicIPv4: ip.address('public', 'ipv4'),
    publicIPv6: ip.address('public', 'ipv6'),
    
    // Private addresses (for internal communication)
    privateIPv4: ip.address('private', 'ipv4'),
    privateIPv6: ip.address('private', 'ipv6'),
    
    // Loopback addresses (for local services)
    loopbackIPv4: ip.loopback('ipv4'),
    loopbackIPv6: ip.loopback('ipv6')
  };
}

console.log(getNetworkConfiguration());