# LazyId
[](https://www.npmjs.com/package/lazyid)
[](https://pypi.org/project/lazyid/)
[](https://packagist.org/packages/niefdev/lazyid)
[](LICENSE)
Minimal 14-character URL-safe unique ID generator based on millisecond timestamp and cryptographically secure random bits.
## Overview
LazyId is a lightweight, cross-platform library for generating and parsing 14-character, URL-safe unique identifiers. Each ID encodes a 42-bit timestamp (milliseconds since Unix epoch, UTC) and a 42-bit cryptographically secure random value, using a custom Base64 alphabet (`ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_`).
No external dependencies. Consistent output across JavaScript, Python, and PHP.
## Features
- **Compact**: Generates 14-character IDs using a URL-safe Base64 alphabet.
- **Timestamp-Based**: Embeds a 42-bit timestamp (milliseconds since 1970-01-01 UTC).
- **Cryptographic Random**: 42 bits of secure random data.
- **Cross-Platform**: Identical output in JavaScript, Python, and PHP.
- **Reversible**: Extract the original timestamp from any ID.
- **No Dependencies**: Uses only standard libraries.
- **Practically Collision-Free**: Safe for massive scale.
## Installation
### JavaScript (Node.js or Browser)
Install via npm:
```bash
npm install lazyid
```
### Python
Install via PyPI:
```bash
pip install lazyid
```
### PHP
Install via Composer:
```bash
composer require niefdev/lazyid
```
## Usage
### JavaScript
```javascript
const lazyid = require("lazyid");
let id = lazyid();
let data = lazyid(id);
// e.g.
// {
// timestamp: '2025-07-17 23:06:41.645',
// random_bit: '001010110011110011010000100101101100010111'
// }
```
### Python
```python
from lazyid import lazyid
id = lazyid()
data = lazyid('ZgZJT4smNKOm1p')
# e.g.
# {'timestamp': datetime.datetime(2025, 7, 18, 7, 32, 38, 500000), 'random_bit': '000110011101110011001100100101010001011011'}
```
### PHP
```php
<?php
require 'vendor/autoload.php';
use function LazyID\lazyid;
$id = lazyid();
$data = lazyid($id);
// e.g.
// array(2) {
// ["timestamp"]=>
// string(23) "2025-07-17 16:10:28.542"
// ["random_bit"]=>
// string(42) "110011101110110100111100101100110000000100"
// }
```
## API Reference
### `lazyid([id: string])`
- **Generate**: Call with no arguments to create a new LazyId string.
- **Parse**: Call with an ID string to extract `{ timestamp, random_bit }`.
**Returns:**
- **JavaScript**: `string` (generate) or `{ timestamp: string, random_bit: string }` (parse)
- **Python**: `str` (generate) or `{ 'timestamp': str, 'random_bit': str }` (parse)
- **PHP**: `string` (generate) or `[ 'timestamp' => string, 'random_bit' => string ]` (parse)
**Throws:** Error if the input string is invalid.
## Structure of LazyId
- **Total Bits**: 84 bits
- **Timestamp**: 42 bits (milliseconds since 1970-01-01 UTC), reversible without loss.
- **Random Data**: 42 bits (cryptographically secure)
- **Encoding**: Custom Base64 (`A-Z`, `a-z`, `0-9`, `-`, `_`)
- **Length**: 14 characters (84 bits encoded)
## Notes
- **Timezone**: All timestamps are UTC+0. Use `toISOString()` in JS, `datetime.utcfromtimestamp()` in Python, and ISO8601 in PHP.
- **Random Quality**: Uses cryptographic random generation (`crypto.randomBytes`, `os.urandom`, `random_bytes`) with no fallback.
- **Interoperability**: IDs generated in one language can be parsed in another.
## Collision Resistance
Combines 42-bit time + 42-bit cryptographic randomness. Practically impossible to collide, even across distributed systems. Safe for use as database keys, slugs, file names, or event IDs.
## Contributing
Contributions 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 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](https://github.com/niefdev)
## Author
Developed by **niefdev**
## Version
Current version: **1.0.0**
## Repository
Source code: https://github.com/niefdev/lazyid
## Homepage
Learn more: https://github.com/niefdev/lazyid#readme
Raw data
{
"_id": null,
"home_page": "https://github.com/niefdev/lazyid",
"name": "lazyid",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": null,
"keywords": "id unique-id short-id uuid identifier base64 timestamp url-safe lazyid niefdev",
"author": "niefdev",
"author_email": "niefdev@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/cc/ea/2afc4d740942439ff1af208352e887e70de75383729dbdd9934cb710c0fe/lazyid-1.1.0.tar.gz",
"platform": null,
"description": "# LazyId\n\n[](https://www.npmjs.com/package/lazyid)\n[](https://pypi.org/project/lazyid/)\n[](https://packagist.org/packages/niefdev/lazyid)\n[](LICENSE)\n\nMinimal 14-character URL-safe unique ID generator based on millisecond timestamp and cryptographically secure random bits.\n\n## Overview\n\nLazyId is a lightweight, cross-platform library for generating and parsing 14-character, URL-safe unique identifiers. Each ID encodes a 42-bit timestamp (milliseconds since Unix epoch, UTC) and a 42-bit cryptographically secure random value, using a custom Base64 alphabet (`ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_`). \n\nNo external dependencies. Consistent output across JavaScript, Python, and PHP.\n\n## Features\n\n- **Compact**: Generates 14-character IDs using a URL-safe Base64 alphabet.\n- **Timestamp-Based**: Embeds a 42-bit timestamp (milliseconds since 1970-01-01 UTC).\n- **Cryptographic Random**: 42 bits of secure random data.\n- **Cross-Platform**: Identical output in JavaScript, Python, and PHP.\n- **Reversible**: Extract the original timestamp from any ID.\n- **No Dependencies**: Uses only standard libraries.\n- **Practically Collision-Free**: Safe for massive scale.\n\n## Installation\n\n### JavaScript (Node.js or Browser)\nInstall via npm:\n```bash\nnpm install lazyid\n```\n\n### Python\nInstall via PyPI:\n```bash\npip install lazyid\n```\n\n### PHP\nInstall via Composer:\n```bash\ncomposer require niefdev/lazyid\n```\n\n## Usage\n\n### JavaScript\n```javascript\nconst lazyid = require(\"lazyid\");\n\nlet id = lazyid();\nlet data = lazyid(id);\n\n// e.g.\n\n// {\n// timestamp: '2025-07-17 23:06:41.645',\n// random_bit: '001010110011110011010000100101101100010111'\n// }\n```\n\n### Python\n```python\nfrom lazyid import lazyid\n\nid = lazyid()\ndata = lazyid('ZgZJT4smNKOm1p')\n\n# e.g.\n\n# {'timestamp': datetime.datetime(2025, 7, 18, 7, 32, 38, 500000), 'random_bit': '000110011101110011001100100101010001011011'}\n```\n\n### PHP\n```php\n<?php\nrequire 'vendor/autoload.php';\n\nuse function LazyID\\lazyid;\n\n$id = lazyid();\n$data = lazyid($id);\n\n// e.g.\n\n// array(2) {\n// [\"timestamp\"]=>\n// string(23) \"2025-07-17 16:10:28.542\"\n// [\"random_bit\"]=>\n// string(42) \"110011101110110100111100101100110000000100\"\n// }\n```\n\n## API Reference\n\n### `lazyid([id: string])`\n- **Generate**: Call with no arguments to create a new LazyId string.\n- **Parse**: Call with an ID string to extract `{ timestamp, random_bit }`.\n\n**Returns:**\n- **JavaScript**: `string` (generate) or `{ timestamp: string, random_bit: string }` (parse)\n- **Python**: `str` (generate) or `{ 'timestamp': str, 'random_bit': str }` (parse)\n- **PHP**: `string` (generate) or `[ 'timestamp' => string, 'random_bit' => string ]` (parse)\n\n**Throws:** Error if the input string is invalid.\n\n## Structure of LazyId\n\n- **Total Bits**: 84 bits\n- **Timestamp**: 42 bits (milliseconds since 1970-01-01 UTC), reversible without loss.\n- **Random Data**: 42 bits (cryptographically secure)\n- **Encoding**: Custom Base64 (`A-Z`, `a-z`, `0-9`, `-`, `_`)\n- **Length**: 14 characters (84 bits encoded)\n\n## Notes\n\n- **Timezone**: All timestamps are UTC+0. Use `toISOString()` in JS, `datetime.utcfromtimestamp()` in Python, and ISO8601 in PHP.\n- **Random Quality**: Uses cryptographic random generation (`crypto.randomBytes`, `os.urandom`, `random_bytes`) with no fallback.\n- **Interoperability**: IDs generated in one language can be parsed in another.\n\n## Collision Resistance\n\nCombines 42-bit time + 42-bit cryptographic randomness. Practically impossible to collide, even across distributed systems. Safe for use as database keys, slugs, file names, or event IDs.\n\n## Contributing\n\nContributions 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 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## Issues\n\nReport bugs or request features at https://github.com/niefdev/lazyid/issues.\n\n## License\n\nMIT \u00a9 [niefdev](https://github.com/niefdev)\n\n## Author\n\nDeveloped by **niefdev**\n\n## Version\n\nCurrent version: **1.0.0**\n\n## Repository\n\nSource code: https://github.com/niefdev/lazyid\n\n## Homepage\n\nLearn more: https://github.com/niefdev/lazyid#readme\n",
"bugtrack_url": null,
"license": null,
"summary": "Minimal 14-character URL-safe unique ID generator based on millisecond timestamp and cryptographically secure random bits.",
"version": "1.1.0",
"project_urls": {
"Bug Reports": "https://github.com/niefdev/lazyid/issues",
"Homepage": "https://github.com/niefdev/lazyid",
"Source": "https://github.com/niefdev/lazyid"
},
"split_keywords": [
"id",
"unique-id",
"short-id",
"uuid",
"identifier",
"base64",
"timestamp",
"url-safe",
"lazyid",
"niefdev"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "5bfb0c2204827a94eab6369d3632ea2b65c4efa6bec2d8ec4155f3045b8c3ccf",
"md5": "60fe3aa12b9f813abbc90e77e8e42a65",
"sha256": "a778a3cfc0214c927cb88ae532cec797c3d8d7aa0acc738928df18857693443c"
},
"downloads": -1,
"filename": "lazyid-1.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "60fe3aa12b9f813abbc90e77e8e42a65",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 4081,
"upload_time": "2025-07-18T00:43:46",
"upload_time_iso_8601": "2025-07-18T00:43:46.245717Z",
"url": "https://files.pythonhosted.org/packages/5b/fb/0c2204827a94eab6369d3632ea2b65c4efa6bec2d8ec4155f3045b8c3ccf/lazyid-1.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "ccea2afc4d740942439ff1af208352e887e70de75383729dbdd9934cb710c0fe",
"md5": "8a4b157cc69b040924090126516a8fe9",
"sha256": "2ff1f4bbe8760c4cc9a96aae2769e9e54f187b9deabd2520642f0b25629d9543"
},
"downloads": -1,
"filename": "lazyid-1.1.0.tar.gz",
"has_sig": false,
"md5_digest": "8a4b157cc69b040924090126516a8fe9",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 4057,
"upload_time": "2025-07-18T00:43:47",
"upload_time_iso_8601": "2025-07-18T00:43:47.402207Z",
"url": "https://files.pythonhosted.org/packages/cc/ea/2afc4d740942439ff1af208352e887e70de75383729dbdd9934cb710c0fe/lazyid-1.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-18 00:43:47",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "niefdev",
"github_project": "lazyid",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "lazyid"
}
JSON
