LazyId

Minimal 16-character URL-safe unique ID generator based on a millisecond timestamp and cryptographically secure random bits.

Overview

LazyId is a lightweight library for generating and parsing 16-character, URL-safe unique identifiers. Each ID consists of two parts: a time component derived from a millisecond timestamp (UTC) and a cryptographically secure random component, which are then encoded using Base36 (0-9, a-z).

No external dependencies. Available for JavaScript, TypeScript, and Python.

Features

• Compact: Generates 16-character IDs using a URL-safe Base36 alphabet.
• Timestamp-Based: The first 8 characters are derived from a millisecond timestamp (since the Unix epoch, UTC).
• Cryptographic Random: The last 8 characters are derived from secure random data.
• Cross-Platform: Available for JavaScript, TypeScript, and Python with identical output.
• Reversible: Extract the original millisecond timestamp from any ID.
• No Dependencies: Uses only standard libraries.
• Practically Collision-Free: Safe for use at a massive scale.

Installation

JavaScript

Install via npm:

npm install lazyid

TypeScript

Install via npm (scoped package):

npm install lazyid

Python

Install via pip:

pip install lazyid

Usage

JavaScript

// CommonJS
const lazyid = require("lazyid");

// ES Modules
import lazyid from "lazyid";

// Generate a new ID
let id = lazyid(); 
// -> Example: 'k2vtbmo2j5ah57z1'

// Extract the timestamp from an ID
let timestamp = lazyid(id);
// -> Example: 1728494747234 (this is an integer millisecond timestamp)

TypeScript

import lazyid from "lazyid";

// Generate a new ID
const id: string = lazyid();
// -> Example: 'k2vtbmo2j5ah57z1'

// Extract the timestamp from an ID
const timestamp: number = lazyid(id);
// -> Example: 1728494747234 (this is an integer millisecond timestamp)

Python

from lazyid import lazyid

# Generate a new ID
new_id = lazyid()
# -> Example: 'k2vtbmo2j5ah57z1'

# Extract the timestamp from an ID
timestamp = lazyid(new_id)
# -> Example: 1728494747234 (this is an integer millisecond timestamp)

API Reference

lazyid([id])

• Generate: Call with no arguments to create a new LazyId string.
• Parse: Call with an ID string to extract the original integer millisecond timestamp.

Parameters:

• id (string, optional): If provided, extract timestamp from this ID string.

Returns:

• JavaScript: string (on generate) or number (on parse).
• TypeScript: string (on generate) or number (on parse) with full type safety.
• Python: str (on generate) or int (on parse).

Throws: Throws an error if the input string is invalid.

Structure of a LazyId

• Total Length: 16 characters.
• Encoding: Base36 (0123456789abcdefghijklmnopqrstuvwxyz).
• Composition: The ID is formed from the combination of two numerical components, encoded into Base36:
  1. Time Component (First 8 characters): Derived from the current millisecond timestamp (Date.now() % 36**8).
  2. Random Component (Last 8 characters): Derived from cryptographically secure random bytes (crypto.randomBytes in JS/TS, os.urandom in Python).

Notes

• Timezone: All timestamps are processed in UTC.
• Random Quality: Uses cryptographic-grade random generators (crypto.randomBytes in JS/TS, os.urandom in Python) with no fallback.
• Interoperability: IDs generated in any language can be correctly parsed in any other supported language.

Collision Resistance

By combining a time component with millisecond precision and a random component with ~2.8 trillion (36^8) possibilities, LazyId collisions are practically impossible, even in distributed systems generating thousands of IDs per millisecond. It is safe for use as database primary keys, URL slugs, filenames, or event IDs.

Contributing

Contributions are welcome! Please submit issues or pull requests to the GitHub repository.

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

Issues

Report bugs or request features at https://github.com/niefdev/lazyid/issues.

License

MIT © niefdev

Author

Developed by niefdev

Repository

Source code: https://github.com/niefdev/lazyid

Homepage

Learn more: https://github.com/niefdev/lazyid#readme