uniqid

A unique hexatridecimal ID generator based on timestamp, process ID, and MAC address. Creates unique identifiers for distributed systems with three variants optimized for different environment constraints.

Package Information

• Package Name: uniqid
• Package Type: npm
• Language: JavaScript
• Installation: npm install uniqid

Core Imports

const uniqid = require('uniqid');

// Access specific methods
const { process, time } = require('uniqid');

ES6/ES2015 modules:

import uniqid from 'uniqid';

// Access specific methods
import { process, time } from 'uniqid';

Basic Usage

const uniqid = require('uniqid');

// Generate full unique IDs (18 bytes) - works across machines and processes
console.log(uniqid()); // -> "4n5pxq24kpiob12og9"
console.log(uniqid()); // -> "4n5pxq24kriob12ogd"

// Add prefix and suffix
console.log(uniqid('user-')); // -> "user-4n5pxq24kpiob12og9"
console.log(uniqid('order-', '-temp')); // -> "order-4n5pxq24kpiob12og9-temp"

// Generate process-specific IDs (12 bytes) - works within single machine
console.log(uniqid.process()); // -> "0te82iob0ucoj"

// Generate time-based IDs (8 bytes) - works within single process
console.log(uniqid.time()); // -> "iob0ucoj"

Capabilities

Full Unique ID Generation

Generates 18-byte unique hexatridecimal IDs that are unique across multiple machines and processes. Combines MAC address, process ID, and timestamp for maximum uniqueness.

/**
 * Generate 18 byte unique IDs based on time, process ID and MAC address
 * @param {string} [prefix] - Optional string to prepend to the generated ID
 * @param {string} [suffix] - Optional string to append to the generated ID
 * @returns {string} Unique hexatridecimal ID
 */
function uniqid(prefix, suffix);

Usage Examples:

// Basic generation
uniqid() // -> "4n5pxq24kpiob12og9"

// With prefix only
uniqid('hello-') // -> "hello-4n5pxq24kpiob12og9"

// With both prefix and suffix
uniqid('hello-', '-goodbye') // -> "hello-4n5pxq24kpiob12og9-goodbye"

// With suffix only (prefix as empty string or undefined)
uniqid('', '-goodbye') // -> "4n5pxq24kpiob12og9-goodbye"
uniqid(undefined, '-goodbye') // -> "4n5pxq24kpiob12og9-goodbye"

Process-Specific ID Generation

Generates 12-byte unique IDs based on process ID and timestamp. Suitable for multi-process applications on a single machine where MAC address uniqueness is not required.

/**
 * Generate 12 byte unique IDs based on time and process ID
 * @param {string} [prefix] - Optional string to prepend to the generated ID
 * @param {string} [suffix] - Optional string to append to the generated ID
 * @returns {string} Process-specific unique hexatridecimal ID
 */
uniqid.process(prefix, suffix);

Usage Examples:

// Basic process ID generation
uniqid.process() // -> "24ieiob0te82"

// With prefix and suffix
uniqid.process('task-', '-pending') // -> "task-24ieiob0te82-pending"

Time-Based ID Generation

Generates 8-byte unique IDs based solely on timestamp. Recommended for single-process applications where process and machine uniqueness is not required.

/**
 * Generate 8 byte unique IDs based on current time only
 * @param {string} [prefix] - Optional string to prepend to the generated ID
 * @param {string} [suffix] - Optional string to append to the generated ID
 * @returns {string} Time-based unique hexatridecimal ID
 */
uniqid.time(prefix, suffix);

Usage Examples:

// Basic time-based generation
uniqid.time() // -> "iob0ucoj"

// With prefix and suffix
uniqid.time('event-', '-log') // -> "event-iob0ucoj-log"

Environment-Specific Behavior

Node.js Environment

• Full functionality: MAC address detection, process ID access, timestamp generation
• ID Components: MAC address + process ID + timestamp
• Uniqueness: Guaranteed across multiple machines and processes

Browser/Webpack Environment

• Limited functionality: No MAC address or process ID available
• Fallback behavior: All methods (uniqid(), uniqid.process(), uniqid.time()) fall back to time-based generation
• ID Components: Timestamp only
• Uniqueness: Guaranteed within single browser tab/process

Browserify Environment

• Limited functionality: Similar to browser/webpack behavior
• Fallback behavior: All methods fall back to time-based generation
• ID Components: Timestamp only

Uniqueness Guarantees

The library provides different levels of uniqueness based on available system information:

1. Machine + Process + Time: Full uniqid() method in Node.js environments

   • Unique across multiple machines and processes
   • 18-byte hexatridecimal strings
   • Components: MAC address + process ID + monotonic timestamp

2. Process + Time: uniqid.process() method

   • Unique across multiple processes on single machine
   • 12-byte hexatridecimal strings
   • Components: process ID + monotonic timestamp

3. Time Only: uniqid.time() method or fallback behavior

   • Unique within single process
   • 8-byte hexatridecimal strings
   • Components: monotonic timestamp only

Internal Implementation Notes

• Monotonic Time: Uses internal now() helper that ensures strictly increasing timestamps even when called rapidly
• MAC Address Detection: Automatically detects first available non-zero MAC address from network interfaces
• Process ID Encoding: Converts process ID to base36 for compact representation
• Webpack Detection: Automatically detects webpack environments and disables MAC/process detection
• Zero Dependencies: No external runtime dependencies