apexid

Zero-dependency, 136-bit, lexicographically sortable ID generator with Base62 encoding and a 16-bit CRC checksum.

Features

• Lexicographically sortable: Generated IDs sort chronologically when sorted alphabetically.
• Tamper-evident: Features a 16-bit CRC checksum to validate integrity and reject corrupted or modified IDs.
• Monotonicity: Guarantees ascending order even when multiple IDs are generated within the same millisecond.
• Clock skew mitigation: Automatically handles system clock drift/rewind.
• CSPRNG entropy: Employs cryptographically secure random numbers for the random component.
• Base62 encoded: Yields clean, url-safe, alphanumeric 23-character strings.
• Zero external dependencies.

Installation

npm install apexid

Usage

Generating IDs

import { ApexIdGenerator } from 'apexid';

const generator = new ApexIdGenerator();
const id = generator.generate();

console.log(id); // Example: "01H2Z4J6K8M0NPQ2R4S6T8V"

Validating IDs

Validation checks the length, characters (Base62), and verifies the embedded checksum.

import { ApexIdGenerator } from 'apexid';

const isValid = ApexIdGenerator.validate('01H2Z4J6K8M0NPQ2R4S6T8V');
console.log(isValid); // true

ID Structure

An ApexID is represented as a 23-character Base62 string (136 bits total). Internally, it is structured as follows:

• Timestamp (48 bits): UNIX epoch timestamp in milliseconds, stored in big-endian byte order to enable chronological sorting.
• Sequence/Counter (8 bits): Tracks monotonicity for IDs generated in the exact same millisecond. Automatically shifts the timestamp forward if more than 255 IDs are generated in a millisecond.
• Entropy (64 bits): Cryptographically secure random bytes to prevent collisions.
• Checksum (16 bits): CRC16-CCITT checksum computed over the timestamp, counter, and entropy bytes to verify authenticity and integrity.

API Reference

ApexIdGenerator

The main class to generate and validate IDs.

new ApexIdGenerator()

Creates a new instance of the generator. Each instance maintains its own internal state for timestamp tracking and monotonic counters to ensure sorting guarantees.

generate(): string

Generates a strictly 23-character Base62 string.

static validate(id: string): boolean

Performs validation on the given string:

• Checks if the string is exactly 23 characters long.
• Decodes the Base62 structure and ensures no invalid characters are present.
• Verifies that the internal 16-bit CRC-16 checksum matches the payload bytes.

Utility Functions

The package also exports underlying utility functions if you need direct access to the byte manipulation layer.

import {
  calculateChecksum,
  encodeBase62,
  decodeBase62,
  getRandomBytes
} from 'apexid';

calculateChecksum(buffer: Uint8Array): number

Calculates the 16-bit CRC-16 checksum of a Uint8Array.

encodeBase62(buffer: Uint8Array): string

Encodes a Uint8Array into a Base62 string.

decodeBase62(str: string): Uint8Array

Decodes a Base62 string back into a Uint8Array.

getRandomBytes(size: number): Uint8Array

Generates a Uint8Array of the specified size containing cryptographically secure random bytes.

License

MIT