Minimal 16-character URL-safe unique ID generator based on a millisecond timestamp, encoded in Base36.
npm install lazyid[](https://www.npmjs.com/package/lazyid)
[](https://www.google.com/search?q=LICENSE)
Minimal 16-character URL-safe unique ID generator based on a millisecond timestamp and cryptographically secure random bits.
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.
-----
- 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.
-----
Install via npm:
``bash`
npm install lazyid
Install via npm (scoped package):
`bash`
npm install lazyid
Install via pip:
`bash`
pip install lazyid
-----
`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
-----
API Reference
$3
- Generate: Call with no arguments to create a new LazyId string.
- Parse: Call with an ID string to extract the original
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`).-----
Report bugs or request features at https://github.com/niefdev/lazyid/issues.
-----
MIT © niefdev
-----
Developed by niefdev
Source code: https://github.com/niefdev/lazyid
Learn more: https://github.com/niefdev/lazyid\#readme