# 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.
## 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:
```bash
npm install lazyid
```
### TypeScript
Install via npm (scoped package):
```bash
npm install lazyid
```
### Python
Install via pip:
```bash
pip install lazyid
```
-----
## Usage
### JavaScript
```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
```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
```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](https://github.com/niefdev/lazyid/issues).
-----
## License
MIT © [niefdev](https://github.com/niefdev)
-----
## Author
Developed by **niefdev**
## Repository
Source code: [https://github.com/niefdev/lazyid](https://github.com/niefdev/lazyid)
## Homepage
Learn more: [https://github.com/niefdev/lazyid\#readme](https://github.com/niefdev/lazyid#readme)
Raw data
{
"_id": null,
"home_page": null,
"name": "lazyid",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "niefdev <niefdev@gmail.com>",
"keywords": "id, unique-id, short-id, uuid, identifier, base36, timestamp, url-safe, lazyid, python",
"author": null,
"author_email": "niefdev <niefdev@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/43/0f/d95054cfc84b9c561088634b954dccb642cd19a687a5e199cd1fea6bb98f/lazyid-2.1.0.tar.gz",
"platform": null,
"description": "# LazyId\n\n[](https://www.npmjs.com/package/lazyid)\n[](https://www.google.com/search?q=LICENSE)\n\nMinimal 16-character URL-safe unique ID generator based on a millisecond timestamp and cryptographically secure random bits.\n\n## Overview\n\nLazyId 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`).\n\nNo external dependencies. Available for JavaScript, TypeScript, and Python.\n\n-----\n\n## Features\n\n - **Compact**: Generates 16-character IDs using a URL-safe Base36 alphabet.\n - **Timestamp-Based**: The first 8 characters are derived from a millisecond timestamp (since the Unix epoch, UTC).\n - **Cryptographic Random**: The last 8 characters are derived from secure random data.\n - **Cross-Platform**: Available for JavaScript, TypeScript, and Python with identical output.\n - **Reversible**: Extract the original millisecond timestamp from any ID.\n - **No Dependencies**: Uses only standard libraries.\n - **Practically Collision-Free**: Safe for use at a massive scale.\n\n-----\n\n## Installation\n\n### JavaScript\n\nInstall via npm:\n\n```bash\nnpm install lazyid\n```\n\n### TypeScript\n\nInstall via npm (scoped package):\n\n```bash\nnpm install lazyid\n```\n\n### Python\n\nInstall via pip:\n\n```bash\npip install lazyid\n```\n\n-----\n\n## Usage\n\n### JavaScript\n\n```javascript\n// CommonJS\nconst lazyid = require(\"lazyid\");\n\n// ES Modules\nimport lazyid from \"lazyid\";\n\n// Generate a new ID\nlet id = lazyid(); \n// -> Example: 'k2vtbmo2j5ah57z1'\n\n// Extract the timestamp from an ID\nlet timestamp = lazyid(id);\n// -> Example: 1728494747234 (this is an integer millisecond timestamp)\n```\n\n### TypeScript\n\n```typescript\nimport lazyid from \"lazyid\";\n\n// Generate a new ID\nconst id: string = lazyid();\n// -> Example: 'k2vtbmo2j5ah57z1'\n\n// Extract the timestamp from an ID\nconst timestamp: number = lazyid(id);\n// -> Example: 1728494747234 (this is an integer millisecond timestamp)\n```\n\n### Python\n\n```python\nfrom lazyid import lazyid\n\n# Generate a new ID\nnew_id = lazyid()\n# -> Example: 'k2vtbmo2j5ah57z1'\n\n# Extract the timestamp from an ID\ntimestamp = lazyid(new_id)\n# -> Example: 1728494747234 (this is an integer millisecond timestamp)\n```\n\n-----\n\n## API Reference\n\n### `lazyid([id])`\n\n - **Generate**: Call with no arguments to create a new LazyId string.\n - **Parse**: Call with an ID string to extract the original `integer` millisecond timestamp.\n\n**Parameters:**\n - `id` (string, optional): If provided, extract timestamp from this ID string.\n\n**Returns:**\n\n - **JavaScript**: `string` (on generate) or `number` (on parse).\n - **TypeScript**: `string` (on generate) or `number` (on parse) with full type safety.\n - **Python**: `str` (on generate) or `int` (on parse).\n\n**Throws:** Throws an error if the input string is invalid.\n\n-----\n\n## Structure of a LazyId\n\n - **Total Length**: 16 characters.\n - **Encoding**: Base36 (`0123456789abcdefghijklmnopqrstuvwxyz`).\n - **Composition**: The ID is formed from the combination of two numerical components, encoded into Base36:\n 1. **Time Component (First 8 characters)**: Derived from the current millisecond timestamp (`Date.now() % 36**8`).\n 2. **Random Component (Last 8 characters)**: Derived from cryptographically secure random bytes (`crypto.randomBytes` in JS/TS, `os.urandom` in Python).\n\n-----\n\n## Notes\n\n - **Timezone**: All timestamps are processed in UTC.\n - **Random Quality**: Uses cryptographic-grade random generators (`crypto.randomBytes` in JS/TS, `os.urandom` in Python) with no fallback.\n - **Interoperability**: IDs generated in any language can be correctly parsed in any other supported language.\n\n-----\n\n## Collision Resistance\n\nBy 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.\n\n-----\n\n## Contributing\n\nContributions are welcome\\! Please submit issues or pull requests to the GitHub repository.\n\n1. Fork the repository.\n2. Create a feature branch (`git checkout -b feature/your-feature`).\n3. Commit your changes (`git commit -m 'Add your feature'`).\n4. Push to the branch (`git push origin feature/your-feature`).\n5. Open a Pull Request.\n\n-----\n\n## Issues\n\nReport bugs or request features at [https://github.com/niefdev/lazyid/issues](https://github.com/niefdev/lazyid/issues).\n\n-----\n\n## License\n\nMIT \u00a9 [niefdev](https://github.com/niefdev)\n\n-----\n\n## Author\n\nDeveloped by **niefdev**\n\n## Repository\n\nSource code: [https://github.com/niefdev/lazyid](https://github.com/niefdev/lazyid)\n\n## Homepage\n\nLearn more: [https://github.com/niefdev/lazyid\\#readme](https://github.com/niefdev/lazyid#readme)\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Minimal 16-character URL-safe unique ID generator based on a millisecond timestamp and cryptographically secure random bits.",
"version": "2.1.0",
"project_urls": {
"Documentation": "https://github.com/niefdev/lazyid#readme",
"Homepage": "https://github.com/niefdev/lazyid",
"Issues": "https://github.com/niefdev/lazyid/issues",
"Repository": "https://github.com/niefdev/lazyid.git"
},
"split_keywords": [
"id",
" unique-id",
" short-id",
" uuid",
" identifier",
" base36",
" timestamp",
" url-safe",
" lazyid",
" python"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "edd63a0f70a10edd49995888607a9d46d8cc5d609291ab8b36c792663c21d60f",
"md5": "a1de5753af9e801ee685961c7eef21c3",
"sha256": "c7a8a3970f0c26ad3fe18055c37e95a722df29a4b04a18e744854a745addfdf3"
},
"downloads": -1,
"filename": "lazyid-2.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a1de5753af9e801ee685961c7eef21c3",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 3782,
"upload_time": "2025-10-14T08:33:03",
"upload_time_iso_8601": "2025-10-14T08:33:03.033232Z",
"url": "https://files.pythonhosted.org/packages/ed/d6/3a0f70a10edd49995888607a9d46d8cc5d609291ab8b36c792663c21d60f/lazyid-2.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "430fd95054cfc84b9c561088634b954dccb642cd19a687a5e199cd1fea6bb98f",
"md5": "f928d50dd960c817697182010f5aad2e",
"sha256": "042b9a4bd1fa04adfdf4cd87acba4e38a00eca54f160ad938759cb8b51ed7664"
},
"downloads": -1,
"filename": "lazyid-2.1.0.tar.gz",
"has_sig": false,
"md5_digest": "f928d50dd960c817697182010f5aad2e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 3945,
"upload_time": "2025-10-14T08:33:04",
"upload_time_iso_8601": "2025-10-14T08:33:04.324030Z",
"url": "https://files.pythonhosted.org/packages/43/0f/d95054cfc84b9c561088634b954dccb642cd19a687a5e199cd1fea6bb98f/lazyid-2.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-14 08:33:04",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "niefdev",
"github_project": "lazyid#readme",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "lazyid"
}