or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

index.md

tile.json

Range Check

Range Check is a comprehensive IP address validation and manipulation library for TypeScript/JavaScript that handles both IPv4 and IPv6 addresses. It provides utilities for validation, version detection, CIDR range checking, private IP detection, address normalization, and IP fingerprinting for analytics and security applications.

Package Information

Package Name: range_check
Package Type: npm
Language: TypeScript (compiled to JavaScript)
Installation: npm install range_check

Core Imports

import {
  isIP,
  version,
  isV4,
  isV6,
  isRange,
  inRange,
  isPrivateIP,
  isIPInRangeOrPrivate,
  storeIP,
  searchIP,
  displayIP,
  IPFingerprint,
  IPFingerprintHashed
} from "range_check";

For CommonJS:

const {
  isIP,
  version,
  isV4,
  isV6,
  isRange,
  inRange,
  isPrivateIP,
  isIPInRangeOrPrivate,
  storeIP,
  searchIP,
  displayIP,
  IPFingerprint,
  IPFingerprintHashed
} = require("range_check");

Basic Usage

import { isIP, version, inRange, isPrivateIP } from "range_check";

// Basic IP validation
console.log(isIP('192.168.1.1')); // true
console.log(isIP('invalid')); // false

// IP version detection
console.log(version('192.168.1.1')); // 4
console.log(version('2001:db8::1')); // 6

// Range checking
console.log(inRange('192.168.1.1', '192.168.0.0/16')); // true
console.log(inRange('10.0.1.5', ['10.0.0.0/8', '192.168.0.0/16'])); // true

// Private IP detection
console.log(isPrivateIP('192.168.1.1')); // true
console.log(isPrivateIP('8.8.8.8')); // false

Capabilities

IP Address Validation

Core IP address validation functionality for checking if strings are valid IP addresses.

/**
 * Checks if a string is a valid IP address (IPv4 or IPv6)
 * @param addr - IP address string to validate
 * @returns True if valid IP address, false otherwise
 */
function isIP(addr: string): boolean;

IP Version Detection

Functions for determining IP address versions and checking specific versions.

/**
 * Returns the IP version number
 * @param addr - IP address string to check
 * @returns 4 for IPv4, 6 for IPv6, 0 for invalid IP
 */
function version(addr: string): number;

/**
 * Checks if IP address is IPv4
 * @param addr - IP address string to check
 * @returns True if IPv4, false otherwise
 */
function isV4(addr: string): boolean;

/**
 * Checks if IP address is IPv6
 * @param addr - IP address string to check
 * @returns True if IPv6, false otherwise
 */
function isV6(addr: string): boolean;

CIDR Range Operations

Functions for validating CIDR ranges and checking if IP addresses fall within specific ranges.

/**
 * Validates if string is a valid CIDR range
 * @param range - CIDR range string to validate (e.g., "10.0.0.0/8")
 * @returns True if valid CIDR range, false otherwise
 */
function isRange(range: string): boolean;

/**
 * Checks if IP address is within specified range(s)
 * @param addr - IP address to check
 * @param range - CIDR range, single IP, or array of ranges
 * @returns True if IP is within any specified range, false otherwise
 */
function inRange(addr: string, range: string | string[]): boolean;

Private IP Detection

Advanced private IP detection with support for IPv4 private ranges, IPv6 unique local addresses, and IPv4-mapped IPv6 addresses.

/**
 * Checks if IP address is private (RFC 1918, RFC 4193, loopback)
 * @param ip - IP address to check
 * @returns True if private IP address, false otherwise
 */
function isPrivateIP(ip: string): boolean;

/**
 * Checks if IP is in specified ranges or is private
 * @param ip - IP address to check
 * @param options - Configuration options
 * @returns True if IP matches criteria, false otherwise
 */
function isIPInRangeOrPrivate(
  ip: string,
  options?: {
    ranges?: string[] | string;
    allowAnyPrivate?: boolean;
  }
): boolean;

The isIPInRangeOrPrivate function supports flexible configuration:

ranges: String or array of CIDR ranges to check against
allowAnyPrivate: Whether to allow any private IP (default: true)

IP Address Normalization

Functions for normalizing IP addresses for consistent storage and display across different representations.

/**
 * Normalizes IP address for consistent storage
 * @param addr - IP address to normalize
 * @returns Normalized IP for storage, null if invalid
 */
function storeIP(addr: string): string | null;

/**
 * Alias for storeIP - normalizes IP address for search operations
 * @param addr - IP address to normalize
 * @returns Normalized IP for search, null if invalid
 */
function searchIP(addr: string): string | null;

/**
 * Formats IP address for display (expands IPv6, converts IPv4-mapped)
 * @param addr - IP address to format
 * @returns Formatted IP for display, empty string if invalid
 */
function displayIP(addr: string): string;

Storage vs Display Behavior:

storeIP/searchIP: IPv6 addresses are abbreviated, IPv4-mapped IPv6 converted to IPv4
displayIP: IPv6 addresses are normalized (expanded), IPv4-mapped IPv6 converted to IPv4

IP Fingerprinting

Advanced IP fingerprinting capabilities for bot tracking, analytics, and rate limiting applications.

/**
 * Generates consistent fingerprint for IP addresses
 * @param addr - IP address to fingerprint
 * @returns Fingerprint in format "v4:ADDRESS" or "v6:PREFIX::"
 * @throws Error if invalid IP address
 */
function IPFingerprint(addr: string): string;

/**
 * Generates SHA-256 hashed fingerprint using Web Crypto API
 * @param addr - IP address to fingerprint
 * @returns Promise resolving to hashed fingerprint "v4:HASH" or "v6:HASH"
 * @throws Error if invalid IP or Web Crypto API unavailable
 */
function IPFingerprintHashed(addr: string): Promise<string>;

Fingerprinting Behavior:

IPv4: Uses full address (e.g., v4:192.168.1.1)
IPv6: Uses /64 network prefix (e.g., v6:2001:db8:1234:5678::)
IPv4-mapped IPv6: Converted to IPv4 format
Hashed version: SHA-256 hash of IP portion only, preserving prefix format

Usage Examples:

// Basic fingerprinting
const fp1 = IPFingerprint('192.168.1.1'); // "v4:192.168.1.1"
const fp2 = IPFingerprint('2001:db8::1'); // "v6:2001:db8:0:0::"

// Hashed fingerprinting for privacy
const hashedFp = await IPFingerprintHashed('192.168.1.1');
// "v4:c5eb5a4cc76a5cdb16e79864b9ccd26c3553f0c396d0a21bafb7be71c1efcd8c"

// Rate limiting example
const userKey = await IPFingerprintHashed(clientIP);
if (tooManyRequests(userKey)) {
  throw new Error('Rate limit exceeded');
}

Types

// Options interface for isIPInRangeOrPrivate function
interface IPRangeOptions {
  ranges?: string[] | string;
  allowAnyPrivate?: boolean;
}

Error Handling

Functions return false, null, 0, or empty string for invalid inputs rather than throwing exceptions, except for:

IPFingerprint: Throws Error for invalid IP addresses
IPFingerprintHashed: Throws Error for invalid IP addresses or when Web Crypto API is unavailable

Browser and Node.js Compatibility

Core functions: Work in all JavaScript environments
IPFingerprintHashed: Requires Web Crypto API support (modern browsers, Node.js 15.0+, Bun)
Dependencies: Uses ipaddr.js for parsing and ip6 for IPv6 normalization

Common Use Cases

Form Validation:

if (!isIP(userInput)) {
  throw new Error('Invalid IP address');
}

Security Filtering:

if (isPrivateIP(clientIP) || inRange(clientIP, allowedRanges)) {
  // Allow request
} else {
  // Block request
}

Database Storage:

const normalizedIP = storeIP(clientIP);
if (normalizedIP) {
  await db.users.update({ lastIP: normalizedIP });
}

Rate Limiting:

const fingerprint = await IPFingerprintHashed(clientIP);
if (await rateLimiter.isExceeded(fingerprint)) {
  throw new Error('Too many requests');
}